Updates based on latest PR feedback

apis/v1alpha2/gateway_types.go

@@ -118,12 +118,22 @@ type GatewaySpec struct {
 	// requested address is invalid or unavailable, the implementation MUST
 	// indicate this in the associated entry in GatewayStatus.Addresses.
 	//
+	// The Addresses field represents a request for the address(es) on the
+	// "outside of the Gateway", that traffic bound for this Gateway will use.
+	// This could be the IP address or hostname of an external load balancer or
+	// other networking infrastructure, or some other address that traffic will
+	// be sent to.
+	//
+	// The .listener.hostname field is used to route traffic that has already
+	// arrived at the Gateway to the correct in-cluster destination.
+	//
 	// If no Addresses are specified, the implementation MAY schedule the
 	// Gateway in an implementation-specific manner, assigning an appropriate
 	// set of Addresses.
 	//
 	// The implementation MUST bind all Listeners to every GatewayAddress that
-	// it assigns to the Gateway.
+	// it assigns to the Gateway and add a corresponding entry in
+	// GatewayStatus.Addresses.
 	//
 	// Support: Core
 	//
@@ -182,8 +192,8 @@ type Listener struct {
 	Protocol ProtocolType `json:"protocol"`
 
 	// TLS is the TLS configuration for the Listener. This field is required if
-	// the Protocol field is "HTTPS" or "TLS". It MUST be ignored when the
-	// Protocol field is "HTTP", "TCP", or "UDP".
+	// the Protocol field is "HTTPS" or "TLS". It is invalid to set this field
+	// if the Protocol field is "HTTP", "TCP", or "UDP".
 	//
 	// The association of SNIs to Certificate defined in GatewayTLSConfig is
 	// defined based on the Hostname field for this listener.
@@ -196,15 +206,15 @@ type Listener struct {
 	// +optional
 	TLS *GatewayTLSConfig `json:"tls,omitempty"`
 
-	// AllowedRoutes specifies which Routes may be attached to this Listener.
+	// AllowedRoutes defines the types of routes that MAY be attached to a
+	// Listener and the trusted namespaces where those Route resources MAY be
+	// present.
 	//
 	// Although a client request may match multiple route rules, only one rule
 	// may ultimately receive the request. Matching precedence MUST be
 	// determined in order of the following criteria:
 	//
-	// * The most specific match as defined by the Route type. For example, the
-	//   most specific HTTPRoute match is determined by the longest matching
-	//   combination of hostname and path.
+	// * The most specific match as defined by the Route type.
 	// * The oldest Route based on creation timestamp. For example, a Route with
 	//   a creation timestamp of "2020-09-08 01:02:03" is given precedence over
 	//   a Route with a creation timestamp of "2020-09-08 01:02:04".
@@ -213,7 +223,7 @@ type Listener struct {
 	//   example, foo/bar is given precedence over foo/baz.
 	//
 	// All valid rules within a Route attached to this Listener should be
-	// supported. Invalid Route rules can be ignored (sometimes that will mean
+	// implemented. Invalid Route rules can be ignored (sometimes that will mean
 	// the full Route). If a Route rule transitions from valid to invalid,
 	// support for that Route rule should be dropped to ensure consistency. For
 	// example, even if a filter specified by a Route rule is invalid, the rest
@@ -357,21 +367,21 @@ type AllowedRoutes struct {
 	Kinds []RouteGroupKind `json:"kinds,omitempty"`
 }
 
-// NamespacesFrom specifies namespace from which Routes may be attached to a
+// FromNamespaces specifies namespace from which Routes may be attached to a
 // Gateway.
 //
 // +kubebuilder:validation:Enum=All;Selector;Same
-type NamespacesFrom string
+type FromNamespaces string
 
 const (
 	// Routes in all namespaces may be attached to this Gateway.
-	NamespacesFromAll NamespacesFrom = "All"
+	NamespacesFromAll FromNamespaces = "All"
 	// Only Routes in namespaces selected by the selector may be attached to
 	// this Gateway.
-	NamespacesFromSelector NamespacesFrom = "Selector"
+	NamespacesFromSelector FromNamespaces = "Selector"
 	// Only Routes in the same namespace as the Gateway may be attached to this
 	// Gateway.
-	NamespacesFromSame NamespacesFrom = "Same"
+	NamespacesFromSame FromNamespaces = "Same"
 )
 
 // RouteNamespaces indicate which namespaces Routes should be selected from.
@@ -387,7 +397,7 @@ type RouteNamespaces struct {
 	//
 	// +optional
 	// +kubebuilder:default=Same
-	From *NamespacesFrom `json:"from,omitempty"`
+	From *FromNamespaces `json:"from,omitempty"`
 
 	// Selector must be specified when From is set to "Selector". In that case,
 	// only Routes in Namespaces matching this Selector will be selected by this
@@ -472,8 +482,6 @@ type GatewayStatus struct {
 	// addresses in the Spec, e.g. if the Gateway automatically
 	// assigns an address from a reserved pool.
 	//
-	// These addresses should all be of type "IPAddress".
-	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=16
 	Addresses []GatewayAddress `json:"addresses,omitempty"`
@@ -538,8 +546,8 @@ const (
 	// true.
 	GatewayReasonScheduled GatewayConditionReason = "Scheduled"
 
-	// This reason is used with the "Scheduled" condition when
-	// been recently created and no controller has reconciled it yet.
+	// This reason is used with the "Scheduled" condition when no controller has
+	// reconciled the Gateway.
 	GatewayReasonNotReconciled GatewayConditionReason = "NotReconciled"
 
 	// This reason is used with the "Scheduled" condition when the
@@ -608,6 +616,12 @@ type ListenerStatus struct {
 	// intersection of those kinds and the kinds supported by the implementation
 	// for the specified protocol.
 	//
+	// If kinds are specified in Spec that are not supported, an implementation
+	// MUST set the "ResolvedRefs" condition to "False" with the
+	// "InvalidRouteKinds" reason. If both valid and invalid Route kinds are
+	// specified, the implementation should support the valid Route kinds that
+	// have been specified.
+	//
 	// +kubebuilder:validation:MaxItems=8
 	SupportedKinds []RouteGroupKind `json:"supportedKinds"`
 
@@ -758,7 +772,7 @@ const (
 
 	// This reason is used with the "ResolvedRefs" condition when an invalid or
 	// unsupported Route kind is specified by the Listener.
-	ListenerReasonInvalidRoutesRef ListenerConditionReason = "InvalidRouteKinds"
+	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

apis/v1alpha2/httproute_types.go

@@ -62,7 +62,7 @@ type HTTPRouteSpec struct {
 	// 1. IPs are not allowed.
 	// 2. The `:` delimiter is not respected because ports are not allowed.
 	//
-	// If a hostname is specified by both the Listener and HTTPRoute, their
+	// If a hostname is specified by both the Listener and HTTPRoute, there
 	// must be at least one intersecting hostname for the HTTPRoute to be
 	// attached to the Listener. For example:
 	//
@@ -80,7 +80,7 @@ type HTTPRouteSpec struct {
 	// HTTPRoute hostnames that do not match the Listener hostname MUST be
 	// ignored. For example, if a Listener specified `*.example.com`, and the
 	// HTTPRoute specified `test.example.com` and `test.example.net`,
-	// `test.example.net` would be ignored.
+	// `test.example.net` must not be considered for a match.
 	//
 	// If hostnames do not match with the criteria above, then the HTTPRoute is
 	// not admitted, and the implementation must raise an 'Admitted' Condition
@@ -143,6 +143,7 @@ type HTTPRouteRule struct {
 	// * The longest matching non-wildcard hostname.
 	// * The longest matching path.
 	// * The largest number of header matches.
+	// * The largest number of query param matches.
 	//
 	// If ties still exist across multiple Routes, matching precedence MUST be
 	// determined in order of the following criteria, continuing on ties:
@@ -185,11 +186,14 @@ type HTTPRouteRule struct {
 	Filters []HTTPRouteFilter `json:"filters,omitempty"`
 
 	// 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 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.
+	// sent.
+
+	// If unspecified or invalid (refers to a non-existent resource or a Service
+	// with no endpoints), the rule performs no forwarding. If that are also no
+	// filters 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
@@ -746,7 +750,7 @@ type HTTPBackendRef struct {
 	// +optional
 	BackendRef `json:",inline"`
 
-	// Filters defined at this-level should be executed if and only if the
+	// Filters defined at this level should be executed if and only if the
 	// request is being forwarded to the backend defined here.
 	//
 	// Support: Custom (For broader support of filters, use the Filters field

apis/v1alpha2/shared_types.go

@@ -203,6 +203,9 @@ type RouteParentStatus struct {
 	// Route, to indicate whether the route has been admitted or rejected by the
 	// Gateway, and why.
 	//
+	// A Route MUST be considered "Admitted" if at least one of the Route's
+	// rules is implemented by the Gateway.
+	//
 	// There are a number of cases where the "Admitted" condition may not be set
 	// due to lack of controller visibility, that includes when:
 	//

apis/v1alpha2/tcproute_types.go

@@ -110,9 +110,9 @@ type TCPRouteRule struct {
 type TCPRouteMatch struct {
 	// ExtensionRef is an optional, implementation-specific extension to the
 	// "match" behavior. For example, resource "mytcproutematcher" in group
-	// "networking.example.net". If the referent cannot be found, the rule is
-	// not included in the route. The controller must ensure the "ResolvedRefs"
-	// condition on the Route status is set to `status: False`.
+	// "networking.example.net". If the referent cannot be found, the rule MUST
+	// not be included in the route. The controller must ensure the
+	// "ResolvedRefs" condition on the Route status is set to `status: False`.
 	//
 	// Support: Custom
 	//

apis/v1alpha2/tlsroute_types.go

@@ -148,10 +148,10 @@ type TLSRouteRule struct {
 // given action.
 type TLSRouteMatch struct {
 	// ExtensionRef is an optional, implementation-specific extension to the
-	// "match" behavior. For example, resource "mytlsroutematcher" in group
-	// "networking.example.net". If the referent cannot be found, the rule is
-	// not included in the route. The controller must ensure the "ResolvedRefs"
-	// condition on the Route status is set to `status: False`.
+	// "match" behavior. For example, resource "mytcproutematcher" in group
+	// "networking.example.net". If the referent cannot be found, the rule MUST
+	// not be included in the route. The controller must ensure the
+	// "ResolvedRefs" condition on the Route status is set to `status: False`.
 	//
 	// Support: Custom
 	//

apis/v1alpha2/udproute_types.go

@@ -109,10 +109,10 @@ type UDPRouteRule struct {
 // given action.
 type UDPRouteMatch struct {
 	// ExtensionRef is an optional, implementation-specific extension to the
-	// "match" behavior. For example, resource "myudproutematcher" in group
-	// "networking.example.net". If the referent cannot be found, the rule is
-	// not included in the route. The controller must ensure the "ResolvedRefs"
-	// condition on the Route status is set to `status: False`.
+	// "match" behavior. For example, resource "mytcproutematcher" in group
+	// "networking.example.net". If the referent cannot be found, the rule MUST
+	// not be included in the route. The controller must ensure the
+	// "ResolvedRefs" condition on the Route status is set to `status: False`.
 	//
 	// Support: Custom
 	//