Tweaks to ReferencePolicy GEP

mkdocs.yml

@@ -33,6 +33,8 @@ nav:
       - API specification: references/spec.md
       - Releases: references/releases.md
       - Implementations: references/implementations.md
+  - Enhancement Proposals:
+      - "709: Cross Namespace References from Routes": geps/gep-709.md
   - Contributing:
       - Developer guide: contributing/devguide.md
       - Gateway Enhancement Proposal: contributing/gep.md

site-src/geps/gep-709.md

@@ -1,6 +1,6 @@
 # GEP-709: Cross Namespace References from Routes
 
-* Issue URL: https://github.com/kubernetes-sigs/gateway-api/issues/709
+* Issue: [#709](https://github.com/kubernetes-sigs/gateway-api/issues/709)
 * Status: Implementable
 
 ## TLDR
@@ -24,16 +24,22 @@ capabilities for cross namespace references:
 
 ## ReferencePolicy
 
-Anytime we allow crossing a namespace boundary, we need to be very cautious. To
-ensure that this feature is safe, we need to enforce a handshake mechanism that
-requires resources in both namespaces to agree to this reference. To accomplish
-that, a new ReferencePolicy resource should be introduced.
+Anytime we allow crossing a namespace boundary, we need to be very cautious.
+In the past, we've seen that forwarding traffic across namespace boundaries is
+a desired feature, but without the kinds of safeguards proposed here,
+[vulnerabilities](https://github.com/kubernetes/kubernetes/issues/103675) can
+emerge.
+
+To ensure that Gateway API is able to safely provide this functionality, we need
+to enforce a handshake mechanism that requires resources in both namespaces to
+agree to this reference. To accomplish that, a new ReferencePolicy resource
+should be introduced.
 
 ![Reference Policy](images/709-referencepolicy.png)
 
 With this model, Routes would be able to directly reference Routes and Services
 in other namespaces. These references would only be considered valid if a
-ReferencePolicy in the target namespace explicitly allowed it. 
+ReferencePolicy in the target namespace explicitly allowed it.
 
 The following example shows how a HTTPRoute in namespace foo could reference
 a Service in namespace bar. In this example a ReferencePolicy in the bar
@@ -69,7 +75,7 @@ spec:
 ```
 
 ### API
-This proposed API is fairly straightforward, but comes with a couple notable
+This proposed API is fairly straightforward, but comes with a few notable
 decisions:
 
 1. Each ReferencePolicy only supports a single From and To section. Additional
@@ -82,8 +88,11 @@ decisions:
    more powerful it may encourage unnecessarily insecure configuration.
 
 ```go
-// ReferencePolicy identifies cross namespace relationships that are trusted for
-// Gateway API.
+// ReferencePolicy identifies kinds of resources in other namespaces that are
+// trusted to reference the specified kinds of resources in the local namespace.
+// Each ReferencePolicy can be used to represent a unique trust relationship.
+// Additional Reference Policies can be used to add to the set of trusted
+// sources of inbound references for the namespace they are defined within.
 type ReferencePolicy struct {
     metav1.TypeMeta   `json:",inline"`
     metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -193,10 +202,11 @@ in favor of some other security mechanism. This MAY only be done if other
 mechanisms like NetworkPolicy can effectively limit cross-namespace references
 by the implementation.
 
-An implementation choosing to take this exception MUST clearly document that
-ReferencePolicy is not honored as well as which alternative safeguards are
-available. Note that this is unlikely to apply to ingress implementations of the
-API and will not apply to all mesh implementations. 
+An implementation choosing to make this exception MUST clearly document that
+ReferencePolicy is not honored by their implementations and detail which
+alternative safeguards are available. Note that this is unlikely to apply to
+ingress implementations of the API and will not apply to all mesh
+implementations.
 
 For an example of the risks involved in cross-namespace references, refer to
 [CVE-2021-25740](https://github.com/kubernetes/kubernetes/issues/103675).
@@ -207,28 +217,30 @@ effective safeguards are in place.
 
 ## ForwardTo
 
-To enable cross-namespace forwarding, we'll need to add a `namespace` field to
-the ForwardTo BackendRef struct.
+To enable cross-namespace forwarding, we'll need to add an optional `namespace`
+field to the ForwardTo BackendRef struct.
 
 ```go
 type BackendRef struct {
     // ...
 
-    // Namespace is the namespace of the referrent.
+    // Namespace is the namespace of the backend. When unspecified, the local
+    // namespace is inferred.
     //
     // Support: Core
     //
     // +kubebuilder:validation:MinLength=1
     // +kubebuilder:validation:MaxLength=253
-    Namespace string `json:"namespace,omitempty"`
+    // +optional
+    Namespace *string `json:"namespace,omitempty"`
 }
 ```
 
 ## Alternatives
 
 ### Inline Config
 Instead of ReferencePolicy, it is possible to represent these relationships
-inline. 
+inline.
 ![Inline](images/709-inline.png)
 
 ```yaml