GEP-1713 Revisions

geps/gep-1713/index.md

@@ -30,14 +30,14 @@ From [Gateway Hierarchy Brainstorming](https://docs.google.com/document/d/1qj7Xo
 ## Use Cases & Motivation
 
 Knative generates on demand per-service certificates using HTTP-01 challenges.
-There can be O(1000) Knative `Services` in the cluster which means we have O(1000) distinct certificates.
+There can be `O(1000) Knative `Services` in the cluster which means we have O(1000) distinct certificates.
 Thus updating a single `Gateway` resource with this many certificates is a contention point and inhibits horizontal scaling of our controllers.
 [Istio Ambient](https://istio.io/v1.15/blog/2022/introducing-ambient-mesh/), similarly, creates a listener per Kubernetes service.
 
 More broadly, large scale gateway users often expose `O(1000)` domains, but are currently limited by the maximum of 64 `listeners`.
 
-The spec currently has language to indicate implementations `MAY` merge `Gateways` resources but does not define any specific requirements for how that should work.
-https://github.com/kubernetes-sigs/gateway-api/blob/541e9fc2b3c2f62915cb58dc0ee5e43e4096b3e2/apis/v1beta1/gateway_types.go#L76-L78
+The [spec currently has language](https://github.com/kubernetes-sigs/gateway-api/blob/541e9fc2b3c2f62915cb58dc0ee5e43e4096b3e2/apis/v1beta1/gateway_types.go#L76-L78) to indicate implementations `MAY` merge `Gateways` resources but does not define any specific requirements for how that should work.
+
 
 ## Feature Details
 
@@ -164,15 +164,18 @@ type ListenerEntry struct {
 	// Port is the network port. Multiple listeners may use the
 	// same port, subject to the Listener compatibility rules.
 	//
-	// If the port is specified as zero, the implementation will assign
+	// If the port is not set or specified as zero, the implementation will assign
 	// a unique port. If the implementation does not support dynamic port
 	// assignment, it MUST set `Accepted` condition to `False` with the
 	// `UnsupportedPort` reason.
 	//
 	// Support: Core
 	//
 	// +optional
-	Port *PortNumber `json:"port,omitempty"`
+	//
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=65535
+	Port int32 `json:"port,omitempty"`
 
 	// Protocol specifies the network protocol this listener expects to receive.
 	//
@@ -385,8 +388,11 @@ spec:
 ```
 ### ListenerEntry
 
-`ListenerEntry` is currently a copy of the `Listener` struct with some changes
-1. `Port` is now a pointer to allow for dynamic port assignment.
+`ListenerEntry` is currently a copy of the `Listener` struct with some changes noted in the below sections
+
+#### Port
+
+`Port` is now optional to allow for dynamic port assignment.  If the port is unspecified or set to zero, the implementation will assign a unique port. If the implementation does not support dynamic port assignment, it MUST set `Accepted` condition to `False` with the `UnsupportedPort` reason.
 
 ## Semantics
 
@@ -399,7 +405,7 @@ When there are no listeners the `Gateway`'s `status.listeners` should be empty o
 
 Implementations, when creating a `Gateway`, may provision underlying infrastructure when there are no listeners present. The status conditions `Accepted` and `Programmed` conditions should reflect state of this provisioning.
 
-### Gateway <> ListenerSet Handshake
+### Gateway & ListenerSet Handshake
 
 By default a `Gateway` MUST NOT allow `ListenerSets` to be attached. Users can enable this behaviour by configuring their `Gateway` to allow `ListenerSet` attachment:
 
@@ -413,7 +419,7 @@ spec:
   - from: Same
 ```
 
-### Route Attaching
+### Route Attachment
 
 Routes MUST be able to specify a `ListenerSet` as a `parentRef`. Routes can use `sectionName`/`port` fields in `ParentReference` to help target a specific listener. If no listener is targeted (`sectionName`/`port` are unset) then the Route attaches to all the listeners in the `ListenerSet`.
 
@@ -461,10 +467,36 @@ spec:
     sectionName: foo
 ```
 
+#### Optional Section Name
+
+If a `sectionName` in a Route's `parentRef` is not set then the Route MUST attach to only the listeners in the referenced parent. As an example given a `Gateway` and it's child `ListenerSets` a route attaching to the `Gateway` with an empty `sectionName` shall only attach to the listeners in the `Gateways` immediate `spec.listeners` list. In other words, the Route will not attach to any listeners in the `ListenerSets`. This is necessary because, for UX reasons, the `name` field does not have to be unique across all Listeners merged into a Gateway (see the section below for details).
+
+### Policy Attachment
+
+Policy attachment is [under discussion] in https://github.com/kubernetes-sigs/gateway-api/discussions/2927
+
+Similar to Routes, `ListenerSet` can inherit policy from a Gateway.
+Policies that attach to a `ListenerSet` apply to all listeners defined in that resource, but do not impact listeners in the parent `Gateway`. This allows `ListenerSets` attached to the same `Gateway` to have different policies.
+If the implementation cannot apply the policy to only specific listeners, it should reject the policy.
+
+### ReferenceGrant Semantics
+
+When a `ReferenceGrant` is applied to a `Gateway` it MUST NOT be inherited by child `ListenerSets`. Thus a `ListenerSet` listener MUST NOT access secrets granted to the `Gateway` listeners.
+
+When a `ReferenceGrant` is applied to a `ListenerSet` it MUST NOT grant permission to the parent `Gateway`'s listeners. Thus a `Gateway` listener MUST NOT access secrets granted to the `ListenerSet` listeners.
+
+A `ListenerSet` must be able to reference a secret/backend in the same namespace as itself without a `ReferenceGrant`.
+
+
 ### Listener Validation
 
-Implementations MUST treat the parent `Gateway`s as having the merged list of all listeners from itself and attached `ListenerSets`. See 'Listener Precedence' for more details on ordering.
-Validation of this list of listeners MUST behave the same as if the list were part of a single `Gateway`.
+Within a single resource such as a `Gateway` or `ListenerSet` the list of listeners MUST have unique names. Implementations MUST allow listeners from a child `ListenerSet` to be merged into a parent `Gateway` when listeners have the same name. Likewise implementations MUST allow sibling `ListenerSets` listeners with matching names to be merged into a parent `Gateway`. This allows for authors of Routes to simply attach to their desired parentRef and listener without having to worry about naming conflicts across resources.
+
+It is up to the implementations how unique names are generated internally. One example would be to hash the `ListenerSet` name+namespace and prepend it to the listener entry `name`.
+
+Implementations MUST treat the parent `Gateway`s as having the merged list of all listeners from itself and attached `ListenerSets` and validation of this list of listeners MUST behave the same as if the list were part of a single `Gateway` with the relaxed listener name constraints.
+
+Ordering will follow the semantics defined in [Listener Precedence](#listener-precedence).
 
 From the earlier example the above resources would be equivalent to a single `Gateway` where the listeners are collapsed into a single list.
 
@@ -514,7 +546,7 @@ Listeners should be merged using the following precedence:
 
 Conflicts are covered in the section 'ListenerConditions within a ListenerSet'
 
-###  Gateway Conditions
+### Gateway Conditions
 
 `Gateway`'s `Accepted` and `Programmed` top-level conditions remain unchanged and reflect the status of the local configuration.
 
@@ -555,14 +587,6 @@ If a listener has a conflict, this should be reported in the `ListenerEntryStatu
 
 Implementations SHOULD be cautious about what information from the parent or siblings are reported to avoid accidentally leaking sensitive information that the child would not otherwise have access to. This can include contents of secrets etc.
 
-### Policy Attachment
-
-Policy attachment is [under discussion] in https://github.com/kubernetes-sigs/gateway-api/discussions/2927
-
-Similar to Routes, `ListenerSet` can inherit policy from a Gateway.
-Policies that attach to a `ListenerSet` apply to all listeners defined in that resource, but do not impact listeners in the parent `Gateway`. This allows `ListenerSets` attached to the same `Gateway` to have different policies.
-If the implementation cannot apply the policy to only specific listeners, it should reject the policy.
-
 ## Alternatives
 
 ### Re-using Gateway Resource