status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

mesh: update various protobuf comments for mesh types (#18993)

This commit is contained in:
R.B. Boyer 2023-09-22 18:41:49 -05:00 committed by GitHub
parent e6b724d062
commit ca7533850c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 95 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
proto-public/pbmesh/v2beta1/common.pb.go
View File

@ -33,33 +33,10 @@ type ParentReference struct {
// For east/west configuration, this should point to a pbcatalog.Service.
// For north/south it should point to a gateway (TBD)
Ref *pbresource.Reference `protobuf:"bytes,1,opt,name=ref,proto3" json:"ref,omitempty"`
// Port is the network port this Route targets. It can be interpreted
// differently based on the type of parent resource.
// For east/west this is the name of the Consul Service port to direct traffic to
// or empty to imply all.
//
// When the parent resource is a Gateway, this targets all listeners
// listening on the specified port that also support this kind of Route(and
// select this Route). It’s not recommended to set Port unless the networking
// behaviors specified in a Route must apply to a specific port as opposed to
// a listener(s) whose port(s) may be changed. When both Port and SectionName
// are specified, the name and port of the selected listener must match both
// specified values.
//
// Implementations MAY choose to support other parent resources.
// Implementations supporting other types of parent resources MUST clearly
// document how/if Port is interpreted.
//
// For the purpose of status, an attachment is considered successful as long
// as the parent resource accepts it partially. For example, Gateway
// listeners can restrict which Routes can attach to them by Route kind,
// namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from
// the referencing Route, the Route MUST be considered successfully attached.
// If no Gateway listeners accept attachment from this Route, the Route MUST
// be considered detached from the Gateway.
//
// For east/west this is the name of the consul port.
// For north/south this is the stringified integer port expected by GAMMA.
//
// https://gateway-api.sigs.k8s.io/geps/gep-957/
// For north/south this is TBD.
Port string `protobuf:"bytes,2,opt,name=port,proto3" json:"port,omitempty"`
}
@ -114,20 +91,13 @@ type BackendReference struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// For east/west configuration, this should point to either a
// pbcatalog.Service or ServiceSubset.
//
// For Partition/PeerName fields likely we could map them to ServiceImports
// (MCS+GAMMA) when translating
// For east/west configuration, this should point to a pbcatalog.Service.
Ref *pbresource.Reference `protobuf:"bytes,1,opt,name=ref,proto3" json:"ref,omitempty"`
// For east/west this is the name of the consul port.
// For east/west this is the name of the Consul Service port to direct traffic to
// or empty to imply using the same value as the parent ref.
//
// For north/south this is TBD.
Port string `protobuf:"bytes,2,opt,name=port,proto3" json:"port,omitempty"`
// NOT IN GAMMA; multi-cluster + GWapi is still unknown
//
// Likely we could map this to ServiceImports (MCS+GAMMA) when translating
// to/from k8s.
//
// https://gateway-api.sigs.k8s.io/geps/gep-1748/
Datacenter string `protobuf:"bytes,3,opt,name=datacenter,proto3" json:"datacenter,omitempty"`
}

47
proto-public/pbmesh/v2beta1/common.proto
View File

@ -13,52 +13,21 @@ message ParentReference {
// For north/south it should point to a gateway (TBD)
hashicorp.consul.resource.Reference ref = 1;
// Port is the network port this Route targets. It can be interpreted
// differently based on the type of parent resource.
// For east/west this is the name of the Consul Service port to direct traffic to
// or empty to imply all.
//
// When the parent resource is a Gateway, this targets all listeners
// listening on the specified port that also support this kind of Route(and
// select this Route). It’s not recommended to set Port unless the networking
// behaviors specified in a Route must apply to a specific port as opposed to
// a listener(s) whose port(s) may be changed. When both Port and SectionName
// are specified, the name and port of the selected listener must match both
// specified values.
//
// Implementations MAY choose to support other parent resources.
// Implementations supporting other types of parent resources MUST clearly
// document how/if Port is interpreted.
//
// For the purpose of status, an attachment is considered successful as long
// as the parent resource accepts it partially. For example, Gateway
// listeners can restrict which Routes can attach to them by Route kind,
// namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from
// the referencing Route, the Route MUST be considered successfully attached.
// If no Gateway listeners accept attachment from this Route, the Route MUST
// be considered detached from the Gateway.
//
// For east/west this is the name of the consul port.
// For north/south this is the stringified integer port expected by GAMMA.
//
// https://gateway-api.sigs.k8s.io/geps/gep-957/
// For north/south this is TBD.
string port = 2;
}
message BackendReference {
// For east/west configuration, this should point to either a
// pbcatalog.Service or ServiceSubset.
//
// For Partition/PeerName fields likely we could map them to ServiceImports
// (MCS+GAMMA) when translating
// For east/west configuration, this should point to a pbcatalog.Service.
hashicorp.consul.resource.Reference ref = 1;
// For east/west this is the name of the consul port.
// For east/west this is the name of the Consul Service port to direct traffic to
// or empty to imply using the same value as the parent ref.
//
// For north/south this is TBD.
string port = 2;
// NOT IN GAMMA; multi-cluster + GWapi is still unknown
//
// Likely we could map this to ServiceImports (MCS+GAMMA) when translating
// to/from k8s.
//
// https://gateway-api.sigs.k8s.io/geps/gep-1748/
string datacenter = 3;
}

35
proto-public/pbmesh/v2beta1/grpc_route.pb.go
View File

@ -84,15 +84,15 @@ type GRPCRoute struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
ParentRefs []*ParentReference `protobuf:"bytes,1,rep,name=parent_refs,json=parentRefs,proto3" json:"parent_refs,omitempty"`
// Hostnames are the hostnames for which this GRPCRoute should respond to requests.
//
// This is only valid for north/south.
Hostnames []string `protobuf:"bytes,2,rep,name=hostnames,proto3" json:"hostnames,omitempty"`
// Rules are a list of GRPC matchers, filters and actions.
Rules []*GRPCRouteRule `protobuf:"bytes,3,rep,name=rules,proto3" json:"rules,omitempty"`
@ -158,10 +158,29 @@ type GRPCRouteRule struct {
Matches []*GRPCRouteMatch `protobuf:"bytes,1,rep,name=matches,proto3" json:"matches,omitempty"`
Filters []*GRPCRouteFilter `protobuf:"bytes,2,rep,name=filters,proto3" json:"filters,omitempty"`
// BackendRefs defines the backend(s) where matching requests should be sent.
//
// Failure behavior here depends on how many BackendRefs are specified and
// how many are invalid.
//
// If all entries in BackendRefs are invalid, and there are also no filters
// specified in this route rule, all traffic which matches this rule MUST
// receive a 500 status code.
//
// See the GRPCBackendRef definition for the rules about what makes a single
// GRPCBackendRef invalid.
//
// When a GRPCBackendRef is invalid, 500 status codes MUST be returned for
// requests that would have otherwise been routed to an invalid backend. If
// multiple backends are specified, and some are invalid, the proportion of
// requests that would otherwise have been routed to an invalid backend MUST
// receive a 500 status code.
//
// For example, if two backends are specified with equal weights, and one is
// invalid, 50 percent of traffic must receive a 500. Implementations may
// choose how that 50 percent is determined.
BackendRefs []*GRPCBackendRef `protobuf:"bytes,3,rep,name=backend_refs,json=backendRefs,proto3" json:"backend_refs,omitempty"`
// ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
Timeouts *HTTPRouteTimeouts `protobuf:"bytes,4,opt,name=timeouts,proto3" json:"timeouts,omitempty"`
// ALTERNATIVE:
Retries *HTTPRouteRetries `protobuf:"bytes,5,opt,name=retries,proto3" json:"retries,omitempty"`
}

36
proto-public/pbmesh/v2beta1/grpc_route.proto
View File

@ -20,16 +20,16 @@ import "pbresource/annotations.proto";
message GRPCRoute {
option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
repeated ParentReference parent_refs = 1;
// Hostnames are the hostnames for which this GRPCRoute should respond to requests.
//
// This is only valid for north/south.
repeated string hostnames = 2;
// Rules are a list of GRPC matchers, filters and actions.
@ -39,11 +39,31 @@ message GRPCRoute {
message GRPCRouteRule {
repeated GRPCRouteMatch matches = 1;
repeated GRPCRouteFilter filters = 2;
// BackendRefs defines the backend(s) where matching requests should be sent.
//
// Failure behavior here depends on how many BackendRefs are specified and
// how many are invalid.
//
// If all entries in BackendRefs are invalid, and there are also no filters
// specified in this route rule, all traffic which matches this rule MUST
// receive a 500 status code.
//
// See the GRPCBackendRef definition for the rules about what makes a single
// GRPCBackendRef invalid.
//
// When a GRPCBackendRef is invalid, 500 status codes MUST be returned for
// requests that would have otherwise been routed to an invalid backend. If
// multiple backends are specified, and some are invalid, the proportion of
// requests that would otherwise have been routed to an invalid backend MUST
// receive a 500 status code.
//
// For example, if two backends are specified with equal weights, and one is
// invalid, 50 percent of traffic must receive a 500. Implementations may
// choose how that 50 percent is determined.
repeated GRPCBackendRef backend_refs = 3;
// ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
HTTPRouteTimeouts timeouts = 4;
// ALTERNATIVE:
HTTPRouteRetries retries = 5;
}

16
proto-public/pbmesh/v2beta1/http_route.pb.go
View File

@ -219,16 +219,15 @@ type HTTPRoute struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
ParentRefs []*ParentReference `protobuf:"bytes,1,rep,name=parent_refs,json=parentRefs,proto3" json:"parent_refs,omitempty"`
// Hostnames are the hostnames for which this HTTPRoute should respond to requests.
//
// This is only valid for north/south.
Hostnames []string `protobuf:"bytes,2,rep,name=hostnames,proto3" json:"hostnames,omitempty"`
// Rules are a list of HTTP-based routing rules that this route should
// use for constructing a routing table.
@ -295,9 +294,6 @@ type HTTPRouteRule struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// Matches specified the matching criteria used in the routing table. If a
// request matches the given HTTPMatch configuration, then traffic is routed
// to services specified in the Services field.
Matches []*HTTPRouteMatch `protobuf:"bytes,1,rep,name=matches,proto3" json:"matches,omitempty"`
Filters []*HTTPRouteFilter `protobuf:"bytes,2,rep,name=filters,proto3" json:"filters,omitempty"`
// BackendRefs defines the backend(s) where matching requests should be sent.
@ -322,9 +318,7 @@ type HTTPRouteRule struct {
// invalid, 50 percent of traffic must receive a 500. Implementations may
// choose how that 50 percent is determined.
BackendRefs []*HTTPBackendRef `protobuf:"bytes,3,rep,name=backend_refs,json=backendRefs,proto3" json:"backend_refs,omitempty"`
// ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
Timeouts *HTTPRouteTimeouts `protobuf:"bytes,4,opt,name=timeouts,proto3" json:"timeouts,omitempty"`
// ALTERNATIVE:
Retries *HTTPRouteRetries `protobuf:"bytes,5,opt,name=retries,proto3" json:"retries,omitempty"`
}

17
proto-public/pbmesh/v2beta1/http_route.proto
View File

@ -19,17 +19,16 @@ import "pbresource/annotations.proto";
message HTTPRoute {
option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
repeated ParentReference parent_refs = 1;
// Hostnames are the hostnames for which this HTTPRoute should respond to requests.
//
// This is only valid for north/south.
repeated string hostnames = 2;
// Rules are a list of HTTP-based routing rules that this route should
@ -40,11 +39,7 @@ message HTTPRoute {
// HTTPRouteRule specifies the routing rules used to determine what upstream
// service an HTTP request is routed to.
message HTTPRouteRule {
// Matches specified the matching criteria used in the routing table. If a
// request matches the given HTTPMatch configuration, then traffic is routed
// to services specified in the Services field.
repeated HTTPRouteMatch matches = 1;
repeated HTTPRouteFilter filters = 2;
// BackendRefs defines the backend(s) where matching requests should be sent.
@ -70,9 +65,7 @@ message HTTPRouteRule {
// choose how that 50 percent is determined.
repeated HTTPBackendRef backend_refs = 3;
// ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
HTTPRouteTimeouts timeouts = 4;
// ALTERNATIVE:
HTTPRouteRetries retries = 5;
}

9
proto-public/pbmesh/v2beta1/tcp_route.pb.go
View File

@ -35,14 +35,11 @@ type TCPRoute struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
ParentRefs []*ParentReference `protobuf:"bytes,1,rep,name=parent_refs,json=parentRefs,proto3" json:"parent_refs,omitempty"`
// Rules are a list of TCP matchers and actions.
Rules []*TCPRouteRule `protobuf:"bytes,2,rep,name=rules,proto3" json:"rules,omitempty"`

9
proto-public/pbmesh/v2beta1/tcp_route.proto
View File

@ -17,14 +17,11 @@ import "pbresource/annotations.proto";
message TCPRoute {
option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
// ParentRefs references the resources (usually Gateways) that a Route wants
// to be attached to. Note that the referenced parent resource needs to allow
// this for the attachment to be complete. For Gateways, that means the
// Gateway needs to allow attachment from Routes of this kind and namespace.
// ParentRefs references the resources (usually Services) that a Route wants
// to be attached to.
//
// It is invalid to reference an identical parent more than once. It is valid
// to reference multiple distinct sections within the same parent resource,
// such as 2 Listeners within a Gateway.
// to reference multiple distinct sections within the same parent resource.
repeated ParentReference parent_refs = 1;
// Rules are a list of TCP matchers and actions.