Clarify docs on invalid serviceName (#756)

* Clarify docs on invalid serviceName

Fixes #638

* update for comments

* Wrap

apis/v1alpha2/httproute_types.go

@@ -237,9 +237,11 @@ type HTTPRouteRule struct {
 	Filters []HTTPRouteFilter `json:"filters,omitempty"`
 
 	// BackendRefs defines the backend(s) where matching requests should be
-	// sent. If unspecified, the rule performs no forwarding. If unspecified and
-	// no filters are specified that would result in a response being sent,
-	// a HTTP 503 status code is returned.
+	// sent. If unspecified or invalid (refers to a non-existent resource or a Service with no endpoints),
+	// the rule performs no forwarding; if no filters are specified that would result in a
+	// response being sent, a HTTP 503 status code is returned. 503 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 503 instead.
 	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource

apis/v1alpha2/tcproute_types.go

@@ -89,7 +89,13 @@ type TCPRouteRule struct {
 	Matches []TCPRouteMatch `json:"matches,omitempty"`
 
 	// BackendRefs defines the backend(s) where matching requests should be
-	// sent.
+	// sent. If unspecified or invalid (refers to a non-existent resource or
+	// a Service with no endpoints), the rule performs no forwarding; if no
+	// filters are specified that would result in a response being sent, the
+	// underlying implementation must actively reject connection attempts to
+	// this backend. Connection rejections must respect weight; if an invalid
+	// backend is requested to have 80% of connection, then 80% of connection
+	// must be rejected instead.
 	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource

apis/v1alpha2/tlsroute_types.go

@@ -124,7 +124,14 @@ type TLSRouteRule struct {
 	Matches []TLSRouteMatch `json:"matches,omitempty"`
 
 	// BackendRefs defines the backend(s) where matching requests should be
-	// sent.
+	// sent. If unspecified or invalid (refers to a non-existent resource or
+	// a Service with no endpoints), the rule performs no forwarding; if no
+	// filters are specified that would result in a response being sent, the
+	// underlying implementation must actively reject request attempts to this
+	// backend, by rejecting the connection or returning a 503 status code.
+	// Request rejections must respect weight; if an invalid backend is
+	// requested to have 80% of requests, then 80% of requests must be rejected
+	// instead.
 	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource

apis/v1alpha2/udproute_types.go

@@ -89,7 +89,13 @@ type UDPRouteRule struct {
 	Matches []UDPRouteMatch `json:"matches,omitempty"`
 
 	// BackendRefs defines the backend(s) where matching requests should be
-	// sent.
+	// sent. If unspecified or invalid (refers to a non-existent resource or
+	// a Service with no endpoints), the rule performs no forwarding; if no
+	// filters are specified that would result in a response being sent, the
+	// underlying implementation must actively reject connection attempts to
+	// this backend. Connection rejections must respect weight; if an invalid
+	// backend is requested to have 80% of connection, then 80% of connection
+	// must be rejected instead.
 	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource