First round of revisions

site-src/geps/gep-709.md

@@ -5,18 +5,22 @@
 
 ## TLDR
 
-This GEP attempts to tackle both cross namespace forwarding and route inclusion.
-These are closely related concepts that can be solved with a new ReferencePolicy
-resource that enables app admins to describe where they trust references from.
+This GEP attempts to enable cross namespace forwarding from Routes and provide a
+way to simplify adding Route inclusion (Routes including other Routes) in the
+future. These are closely related concepts that can be solved with a new
+ReferencePolicy resource that enables app admins to describe where they trust
+references from.
 
 ## Motivation/User Journeys/Background
 
-This GEP enables the following capabilities:
+This GEP keeps same namespace references simple while enabling the following
+capabilities for cross namespace references:
 
 1. Retaining full control of Gateway and Routes in an infra namespace, while
    targeting apps in different namespaces.
 1. Traffic splitting between Services in different namespaces.
-1. Mesh overrides to target Services in different namespaces. 
+1. Mesh overrides to target Services in different namespaces. (For more info,
+   see GEP [#713](https://github.com/kubernetes-sigs/gateway-api/issues/713))
 
 ## ReferencePolicy
 
@@ -71,7 +75,9 @@ decisions:
 1. Each ReferencePolicy only supports a single From and To section. Additional
    trust relationships can be modeled with additional ReferencePolicy resources.
 1. Resource names are intentionally excluded from this policy for simplicity and
-   because they rarely provide any meaningful protection.
+   because they rarely provide any meaningful protection. A user that is able
+   to write to resources of a certain kind within a namespace can always rename
+   resources or change the structure of the resources to match a given policy.
 1. A single Namespace is allowed per "From" struct. Although a selector would be
    more powerful it may encourage unnecessarily insecure configuration.
 
@@ -91,15 +97,19 @@ type ReferencePolicy struct {
 // for Gateway API.
 type ReferencePolicySpec struct {
     // From describes the trusted namespaces and kinds that can reference the
-    // resources described in "To".
+    // resources described in "To". Each entry in this list must be considered
+    // to be an additional place that references can be valid from, or to put
+    // this another way, entries must be combined using OR.
     //
     // Support: Core
     //
     // +kubebuilder:validation:MinItems=1
     From []ReferencePolicyFrom `json:"from"`
 
     // To describes the resources that may be referenced by the resources
-    // described in "From".
+    // described in "From". Each entry in this list must be considered to be an
+    // additional place that references can be valid to, or to put this another
+    // way, entries must be combined using OR.
     //
     // Support: Core
     //
@@ -117,9 +127,14 @@ type ReferencePolicyFrom struct {
     // +kubebuilder:validation:MaxLength=253
     Group string `json:"group"`
 
-    // Kind is kind of the referrent.
+    // Kind is the kind of the referrent. Although implementations may support
+    // additional resources, the following Route types are part of the "Core"
+    // support level for this field:
     //
-    // Support: Core
+    // * HTTPRoute
+    // * TCPRoute
+    // * TLSRoute
+    // * UDPRoute
     //
     // +kubebuilder:validation:MinLength=1
     // +kubebuilder:validation:MaxLength=253
@@ -134,7 +149,8 @@ type ReferencePolicyFrom struct {
     Namespace string `json:"namespace,omitempty"`
 }
 
-// ReferencePolicyTo describes trusted kinds.
+// ReferencePolicyTo describes what Kinds are allowed as targets of the
+// references.
 type ReferencePolicyTo struct {
     // Group is the group of the referrent.
     //
@@ -144,9 +160,15 @@ type ReferencePolicyTo struct {
     // +kubebuilder:validation:MaxLength=253
     Group string `json:"group"`
 
-    // Kind is kind of the referrent.
+    // Kind is the kind of the referrent. Although implementations may support
+    // additional resources, the following types are part of the "Core"
+    // support level for this field:
     //
-    // Support: Core
+    // * Service
+    // * HTTPRoute
+    // * TCPRoute
+    // * TLSRoute
+    // * UDPRoute
     //
     // +kubebuilder:validation:MinLength=1
     // +kubebuilder:validation:MaxLength=253
@@ -166,15 +188,22 @@ type ReferencePolicyTo struct {
   separate handshake config on each Service or Route resource.
 
 #### Exceptions
-If traffic is originating from the same location as the configured Route (such
-as sidecars in some mesh implementations) implementations may choose to ignore
-ReferencePolicy. This should only be done if:
-* Other mechanisms like NetworkPolicy can be used to effectively limit
-  cross-namespace references.
-* The implementation clearly documents that ReferencePolicy is not honored.
-
-This exception is very unlikely to apply to any ingress implementations of the
-API and will not apply to all mesh implementations.
+There are some situations where it MAY be acceptable to ignore ReferencePolicy
+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. 
+
+For an example of the risks involved in cross-namespace references, refer to
+[CVE-2021-25740](https://github.com/kubernetes/kubernetes/issues/103675).
+Implementations of this API need to be very careful to avoid confused deputy
+attacks. ReferencePolicy provides a safeguard for that. Exceptions MUST only
+be made by implementations that are absolutely certain that other equally
+effective safeguards are in place.
 
 ## ForwardTo