Review comments

apis/v1alpha2/grpcroute_types.go

@@ -94,6 +94,10 @@ type GRPCRouteSpec struct {
 	//   `test.example.com` and `*.example.com` would both match. On the other
 	//   hand, `example.com` and `test.example.net` would not match.
 	//
+	// Hostnames that are prefixed with a wildcard label (`*.`) are interpreted
+	// as a suffix match. That means that a match for `*.example.com` would match
+	// both `test.example.com`, and `foo.test.example.com`, but not `example.com`.
+	//
 	// If both the Listener and GRPCRoute have specified hostnames, any
 	// GRPCRoute hostnames that do not match the Listener hostname MUST be
 	// ignored. For example, if a Listener specified `*.example.com`, and the
@@ -208,13 +212,26 @@ type GRPCRouteRule struct {
 
 	// BackendRefs defines the backend(s) where matching requests should be
 	// sent.
-
-	// If unspecified or invalid (refers to a non-existent resource or a Service
-	// with no endpoints), the rule performs no forwarding. If there are also no
-	// filters specified that would result in a response being sent, a gRPC `UNAVAILABLE`
-	// status is returned. `UNAVAILABLE` responses must be sent so that the overall
-	// weight is respected; if an invalid backend is requested to have 80% of
-	// requests, then 80% of requests must get a `UNAVAILABLE` instead.
+	//
+	// An `UNIMPLEMENTED` status MUST be returned if there are no BackendRefs or filters
+	// specified that would result in a response being sent.
+	//
+	// A BackendRef is considered invalid when it refers to:
+	//
+	// * an unknown or unsupported kind of resource
+	// * a resource that does not exist
+	// * a resource in another namespace when the reference has not been
+	//   explicitly allowed by a ReferenceGrant (or equivalent concept).
+	//
+	// When a BackendRef is invalid, `UNIMPLEMENTED` statuses 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 an `UNIMPLEMENTED` status.
+	//
+	// When a BackendRef refers to a Service that has no ready endpoints, it is
+	// recommended to return an `UNAVAILABLE` status.
+	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource
 	//
@@ -233,8 +250,8 @@ type GRPCRouteRule struct {
 // is `foo` AND it contains the `version: v1` header:
 //
 // ```
-// match:
-//   method:
+// matches:
+// - method:
 //     type: Exact
 //     service: "foo"
 //   headers:
@@ -384,8 +401,6 @@ type GRPCRouteFilter struct {
 	//
 	// Support: Core
 	//
-	// Support: Core
-	//
 	// +optional
 	RequestHeaderModifier *HTTPRequestHeaderFilter `json:"requestHeaderModifier,omitempty"`
 
@@ -404,7 +419,6 @@ type GRPCRouteFilter struct {
 	// extended filters.
 	//
 	// Support: Implementation-specific
-	// Support: Implementation-specific
 	//
 	// +optional
 	ExtensionRef *LocalObjectReference `json:"extensionRef,omitempty"`
@@ -431,7 +445,7 @@ type GRPCBackendRef struct {
 	// Support: Custom
 	//
 	// +optional
-	BackendRefs []BackendRef `json:",inline"`
+	BackendRefs BackendRef `json:",inline"`
 
 	// Filters defined at this level should be executed if and only if the
 	// request is being forwarded to the backend defined here.

apis/v1alpha2/httproute_types.go

@@ -93,6 +93,13 @@ type HTTPRouteSpec struct {
 	// implementation must raise an 'Accepted' Condition with a status of
 	// `False` in the corresponding RouteParentStatus.
 	//
+	// If a Route (A) of type HTTPRoute or GRPCRoute is attached to a
+	// Listener and that listener already has another Route (B) of the other
+	// type attached and the intersection of the hostnames of A and B is
+	// non-empty, then the implementation must reject Route A. That is, the
+	// implementation must raise an 'Accepted' condition with a status of
+	// 'False' in the corresponding RouteParentStatus.
+	//
 	// Support: Core
 	//
 	// +optional