Fix PR comments and update v1beta1 resources

Signed-off-by: Nick Young <ynick@vmware.com>

apis/v1alpha2/httproute_types.go

@@ -219,7 +219,8 @@ type HTTPRouteRule struct {
 	// 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 randomly receive a 500.
+	// invalid, 50 percent of traffic must receive a 500. Implementations may
+	// choose how that 50 percent is determined.
 	//
 	// When a HTTPBackendRef refers to a Service that has no ready endpoints,
 	// implementations MAY return a 503 for requests to that backend instead.

apis/v1beta1/httproute_types.go

@@ -201,26 +201,31 @@ type HTTPRouteRule struct {
 	// BackendRefs defines the backend(s) where matching requests should be
 	// sent.
 	//
-	// A 500 status code MUST be returned if there are no BackendRefs or filters
-	// specified that would result in a response being sent.
+	// Failure behavior here depends on how many BackendRefs are specified and
+	// how many are invalid.
 	//
-	// A BackendRef is considered invalid when it refers to:
+	// 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
+	// recieve a 500 status code (exactly).
 	//
-	// * 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).
+	// See the HTTPBackendRef definition for the rules about what makes a single
+	// HTTPBackendRef invalid.
 	//
-	// When a BackendRef is invalid, 500 status codes MUST be returned for
+	// When a HTTPBackendRef 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.
 	//
-	// When a BackendRef refers to a Service that has no ready endpoints, it is
-	// recommended to return a 503 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.
+	//
+	// When a HTTPBackendRef refers to a Service that has no ready endpoints,
+	// implementations MAY return a 503 for requests to that backend instead.
 	//
 	// Support: Core for Kubernetes Service
+	//
 	// Support: Custom for any other resource
 	//
 	// Support for weight: Core
@@ -874,21 +879,31 @@ type HTTPRequestMirrorFilter struct {
 type HTTPBackendRef struct {
 	// BackendRef is a reference to a backend to forward matched requests to.
 	//
-	// If the referent cannot be found, this HTTPBackendRef is invalid and must
-	// be dropped from the Gateway. The controller must ensure the
-	// "ResolvedRefs" condition on the Route is set to `status: False` and not
-	// configure this backend in the underlying implementation.
+	// A BackendRef can be invalid for the following reasons. In all cases, the
+	// implementation MUST ensure the `ResolvedRefs` Condition on the Route
+	// is set to `status: False`, with a Reason and Message that indicate
+	// what is the cause of the error.
 	//
-	// If there is a cross-namespace reference to an *existing* object
-	// that is not covered by a ReferenceGrant, the controller must ensure the
-	// "ResolvedRefs"  condition on the Route is set to `status: False`,
-	// with the "RefNotPermitted" reason and not configure this backend in the
-	// underlying implementation.
+	// A BackendRef is invalid if:
 	//
-	// In either error case, the Message of the `ResolvedRefs` Condition
-	// should be used to provide more detail about the problem.
+	// * It refers to an unknown or unsupported kind of resource. In this
+	//   case, the Reason must be set to `InvalidKind` and Message of the
+	//   Condition must explain which kind of resource is unknown or unsupported.
 	//
-	// Support: Custom
+	// * It refers to a resource that does not exist. In this case, the Reason must
+	//   be set to `BackendNotFound` and the Message of the Condition must explain
+	//   which resource does not exist.
+	//
+	// * It refers a resource in another namespace when the reference has not been
+	//   explicitly allowed by a ReferenceGrant (or equivalent concept). In this
+	//   case, the Reason must be set to `RefNotPermitted` and the Message of the
+	//   Condition must explain which cross-namespace reference is not allowed.
+	//
+	// Support: Core for Kubernetes Service
+	//
+	// Support: Custom for any other resource
+	//
+	// Support for weight: Core
 	//
 	// +optional
 	BackendRef `json:",inline"`

apis/v1beta1/shared_types.go

@@ -242,6 +242,15 @@ const (
 	// another namespace, where the object in the other namespace does
 	// not have a ReferenceGrant explicitly allowing the reference.
 	RouteReasonRefNotPermitted RouteConditionReason = "RefNotPermitted"
+
+	// This reason is used with the "ResolvedRefs" condition when
+	// one of the Route's rules has a reference to an unknown or unsupported
+	// Group and/or Kind.
+	RouteReasonInvalidKind RouteConditionReason = "InvalidKind"
+
+	// This reason is used with the "ResolvedRefs" condition when
+	// one of the Route's rules has a reference to a resource that does not exist.
+	RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
 )
 
 // RouteParentStatus describes the status of a route with respect to an

conformance/tests/httproute-invalid-cross-namespace-backend-ref.go

@@ -46,7 +46,7 @@ var HTTPRouteInvalidCrossNamespaceBackendRef = suite.ConformanceTest{
 		// The Route must be Attached.
 		gwAddr := kubernetes.GatewayAndHTTPRoutesMustBeReady(t, suite.Client, suite.ControllerName, kubernetes.NewGatewayRef(gwNN), routeNN)
 
-		t.Run("HTTPRoute with only a nonexistent BackendRef has a ResolvedRefs Condition with status False and Reason RefNotPermitted", func(t *testing.T) {
+		t.Run("HTTPRoute with a cross-namespace BackendRef and no ReferenceGrant has a ResolvedRefs Condition with status False and Reason RefNotPermitted", func(t *testing.T) {
 
 			resolvedRefsCond := metav1.Condition{
 				Type:   string(v1alpha2.RouteConditionResolvedRefs),