Document behavior for missing referents

For each API field that specifies an object reference, document the
expected behavior when the field's referent cannot be found.

* api/v1alpha1/gateway_types.go (GatewaySpec, Listener, ListenerTLS):
* api/v1alpha1/gatewayclass_types.go (GatewayClassSpec):
* api/v1alpha1/httproute_types.go (HTTPRouteHost, HTTPRouteMatch)
(HTTPRouteFilter, HTTPRouteAction): Document behavior for missing
referents.

Author: Miciah

api/v1alpha1/gateway_types.go

@@ -63,6 +63,9 @@ type GatewaySpec struct {
 	// "httproute" or "tcproute" in group "networking.x.k8s.io". However, an
 	// implementation may support other resources.
 	//
+	// If a referent cannot be found, the Gateway's "InvalidRoutes" status
+	// condition will be true.
+	//
 	// If unspecified, no routes will be associated to the Gateway.
 	//
 	// Support: Core
@@ -123,7 +126,8 @@ type Listener struct {
 	// resource (for example, resource "mylistener" in group
 	// "networking.acme.io").  Omitting or specifying the empty string for
 	// both the resource and group indicates that the resource is a
-	// configmap.
+	// configmap.  If the referent cannot be found, the listener's
+	// "InvalidListener" status condition will be true.
 	//
 	// Support: custom.
 	// +optional
@@ -191,7 +195,9 @@ type ListenerTLS struct {
 	// an entry in this list omits or specifies the empty string for both
 	// the group and the resource, the resource defaults to "secret".  An
 	// implementation may support other resources (for example, resource
-	// "mycertificate" in group "networking.acme.io").
+	// "mycertificate" in group "networking.acme.io").  If a referent cannot
+	// be found, the listener's "InvalidListener" status condition will be
+	// true.
 	//
 	// Support: Core (Kubernetes Secrets)
 	// Support: Implementation-specific (Other resource types)

api/v1alpha1/gatewayclass_types.go

@@ -70,7 +70,9 @@ type GatewayClassSpec struct {
 	// include "configmap" (omit or specify the empty string for the group
 	// to indicate the core API group) or a custom resource (CRD).  Omitting
 	// or specifying the empty string for both the resource and group
-	// indicates that the resource is a configmap.
+	// indicates that the resource is a configmap.  If the referent cannot
+	// be found, the GatewayClass's "InvalidParameters" status condition
+	// will be true.
 	//
 	// Support: Custom
 	//

api/v1alpha1/httproute_types.go

@@ -60,7 +60,9 @@ type HTTPRouteHost struct {
 	// empty string for the group) or an implementation-defined resource
 	// (for example, resource "myroutehost" in group "networking.acme.io").
 	// Omitting or specifying the empty string for both the resource and
-	// group indicates that the resource is a configmap.
+	// group indicates that the resource is a configmap.  If the referent
+	// cannot be found, the "InvalidRoute" status condition on any Gateway
+	// that includes the HTTPRoute will be true.
 	//
 	// Support: custom
 	//
@@ -128,7 +130,9 @@ type HTTPRouteMatch struct {
 	// string for the group) or an implementation-defined resource (for
 	// example, resource "myroutematcher" in group "networking.acme.io").
 	// Omitting or specifying the empty string for both the resource and
-	// group indicates that the resource is a configmap.
+	// group indicates that the resource is a configmap.  If the referent
+	// cannot be found, the "InvalidRoute" status condition on any Gateway
+	// that includes the HTTPRoute will be true.
 	//
 	// Support: custom
 	//
@@ -156,7 +160,9 @@ type HTTPRouteFilter struct {
 	// string for the group) or an implementation-defined resource (for
 	// example, resource "myroutefilter" in group "networking.acme.io").
 	// Omitting or specifying the empty string for both the resource and
-	// group indicates that the resource is a configmap.
+	// group indicates that the resource is a configmap.  If the referent
+	// cannot be found, the "InvalidRoute" status condition on any Gateway
+	// that includes the HTTPRoute will be true.
 	//
 	// Support: custom
 	//
@@ -219,15 +225,19 @@ type HTTPRouteAction struct {
 	// implementation may support other resources (for example, resource
 	// "myroutetarget" in group "networking.acme.io").  Omitting or
 	// specifying the empty string for both the resource and group indicates
-	// that the resource is a service.
+	// that the resource is a service.  If the referent cannot be found, the
+	// "InvalidRoute" status condition on any Gateway that includes the
+	// HTTPRoute will be true.
 	ForwardTo *RouteActionTargetObjectReference `json:"forwardTo" protobuf:"bytes,1,opt,name=forwardTo"`
 
 	// Extension is an optional, implementation-specific extension to the
 	// "action" behavior.  The resource may be "configmap" (use the empty
 	// string for the group) or an implementation-defined resource (for
 	// example, resource "myrouteaction" in group "networking.acme.io").
 	// Omitting or specifying the empty string for both the resource and
-	// group indicates that the resource is a configmap.
+	// group indicates that the resource is a configmap.  If the referent
+	// cannot be found, the "InvalidRoute" status condition on any Gateway
+	// that includes the HTTPRoute will be true.
 	//
 	// Support: custom
 	//