chore: Review feedback from Shane Utt

Add security notes on the Gateway side

Co-authored-by: Shane Utt <[email protected]>

Signed-off-by: Flynn <[email protected]>

Author: kflynn

apis/v1/gateway_types.go

@@ -295,12 +295,22 @@ type GatewaySpec struct {
 	// <gateway:experimental>
 	TLS *GatewayTLSConfig `json:"tls,omitempty"`
 
-	// DefaultScope defines the default scope for this Gateway. If unset or
-	// set to the empty string `""` (the default), the Gateway will not
-	// act as a default Gateway; if set, the
-	// Gateway will claim any Route with a matching scope set in its
-	// UseDefaultGateway field, subject to the usual rules about which routes
-	// the Gateway can attach to.
+	// DefaultScope when set configures the Gateway as a default Gateway, meaning
+	// it will dynamically and implicitly have Routes (e.g. HTTPRoute) attached
+	// to it, according to the scope configured here.
+	//
+	// If unset or set to the empty string `""` (the default), the Gateway will not
+	// act as a default Gateway; if set, the Gateway will claim any Route with a
+	// matching scope set in its UseDefaultGateway field, subject to the usual
+	// rules about which routes the Gateway can attach to.
+	//
+	// Think carefully before using this functionality! While the normal rules about
+	// which Route can apply are still enforced, it is simply easier for the wrong
+	// Route to be accidentally attached to this Gateway in this configuration. If the
+	// Gateway operator is not also the operator in control of the scope (e.g.
+	// namespace) with tight controls and checks on what kind of workloads and
+	// Routes get added in that scope, we strongly recommend not using this just
+	// because it seems convenient, and instead stick to explicit Route attachment.
 	//
 	// +optional
 	// <gateway:experimental>

apis/v1/shared_types.go

@@ -241,7 +241,7 @@ type CommonRouteSpec struct {
 	// <gateway:experimental:validation:XValidation:message="sectionName or port must be unique when parentRefs includes 2 or more references to the same parent",rule="self.all(p1, self.exists_one(p2, p1.group == p2.group && p1.kind == p2.kind && p1.name == p2.name && (((!has(p1.__namespace__) || p1.__namespace__ == '') && (!has(p2.__namespace__) || p2.__namespace__ == '')) || (has(p1.__namespace__) && has(p2.__namespace__) && p1.__namespace__ == p2.__namespace__ )) && (((!has(p1.sectionName) || p1.sectionName == '') && (!has(p2.sectionName) || p2.sectionName == '')) || ( has(p1.sectionName) && has(p2.sectionName) && p1.sectionName == p2.sectionName)) && (((!has(p1.port) || p1.port == 0) && (!has(p2.port) || p2.port == 0)) || (has(p1.port) && has(p2.port) && p1.port == p2.port))))">
 	ParentRefs []ParentReference `json:"parentRefs,omitempty"`
 
-	// useDefaultGateway indicates the default Gateway scope to use for this
+	// UseDefaultGateway indicates the default Gateway scope to use for this
 	// Route. If unset (the default), the Route will not be attached to any
 	// default Gateway; if set, it will be attached to any default Gateway
 	// supporting the named scope, subject to the usual rules about which
@@ -251,7 +251,8 @@ type CommonRouteSpec struct {
 	// Gateways supporting the requested scope can change over time without
 	// any notice to the Route author, and in many situations it will not be
 	// appropriate to request a default Gateway for a given Route -- for
-	// example, a Route with specific security needs should almost certainly
+	// example, a Route with specific security requirements should almost certainly
+	// not use a default Gateway.
 	// not use a default Gateway.
 	//
 	// +optional <gateway:experimental>