Gateway API docs updated

The ListenerReasonRefNotPermitted documentation has been improved to
specify that this reason can be triggered by either an unpermitted
BackendRef or an unpermitted CertificateRef.
Besides, the ListenerReasonInvalidCertificateRef documentation has
been improved to specify better what makes a listener CertificateRef
invalid.

Signed-off-by: Mattia Lavacca <lavacca.mattia@gmail.com>

apis/v1alpha2/gateway_types.go

@@ -397,17 +397,24 @@ const (
 
 	// This reason is used with the "ResolvedRefs" condition when the
 	// Listener has a TLS configuration with at least one TLS CertificateRef
-	// that is invalid or cannot be resolved.
+	// that is invalid or does not exist.
+	// A CertificateRef is considered invalid when it refers to a nonexistent
+	// or unsupported resource or kind, or when the data within that resource
+	// is malformed.
+	// This reason must be used only when the reference is granted, which means
+	// that if the referenced secret is invalid or does not exist, but the
+	// reference is not allowed because of the lack of a ReferenceGrant, the
+	// reason RefNotPermitted must be used.
 	ListenerReasonInvalidCertificateRef ListenerConditionReason = "InvalidCertificateRef"
 
 	// This reason is used with the "ResolvedRefs" condition when an invalid or
 	// unsupported Route kind is specified by the Listener.
 	ListenerReasonInvalidRouteKinds ListenerConditionReason = "InvalidRouteKinds"
 
-	// This reason is used with the "ResolvedRefs" condition when
-	// one of the Listener's Routes has a BackendRef to an object in
-	// another namespace, where the object in the other namespace does
-	// not have a ReferenceGrant explicitly allowing the reference.
+	// This reason is used with the "ResolvedRefs" condition when the
+	// Listener has a TLS configuration that references an object in another
+	// namespace, where the object in the other namespace does not have a
+	// ReferenceGrant explicitly allowing the reference.
 	ListenerReasonRefNotPermitted ListenerConditionReason = "RefNotPermitted"
 )
 

apis/v1beta1/gateway_types.go

@@ -747,17 +747,24 @@ const (
 
 	// This reason is used with the "ResolvedRefs" condition when the
 	// Listener has a TLS configuration with at least one TLS CertificateRef
-	// that is invalid or cannot be resolved.
+	// that is invalid or does not exist.
+	// A CertificateRef is considered invalid when it refers to a nonexistent
+	// or unsupported resource or kind, or when the data within that resource
+	// is malformed.
+	// This reason must be used only when the reference is granted, which means
+	// that if the referenced secret is invalid or does not exist, but the
+	// reference is not allowed because of the lack of a ReferenceGrant, the
+	// reason RefNotPermitted must be used.
 	ListenerReasonInvalidCertificateRef ListenerConditionReason = "InvalidCertificateRef"
 
 	// This reason is used with the "ResolvedRefs" condition when an invalid or
 	// unsupported Route kind is specified by the Listener.
 	ListenerReasonInvalidRouteKinds ListenerConditionReason = "InvalidRouteKinds"
 
-	// This reason is used with the "ResolvedRefs" condition when
-	// one of the Listener's Routes has a BackendRef to an object in
-	// another namespace, where the object in the other namespace does
-	// not have a ReferenceGrant explicitly allowing the reference.
+	// This reason is used with the "ResolvedRefs" condition when the
+	// Listener has a TLS configuration that references an object in another
+	// namespace, where the object in the other namespace does not have a
+	// ReferenceGrant explicitly allowing the reference.
 	ListenerReasonRefNotPermitted ListenerConditionReason = "RefNotPermitted"
 )