Adding rationale section, clarifying the conceptual change

mkdocs.yml

@@ -22,23 +22,24 @@ nav:
       Gateway: api-types/gateway.md
       HTTPRoute: api-types/httproute.md
   - Guides:
-      - Getting started: guides/getting-started.md
-      - Simple Gateway: guides/simple-gateway.md
-      - HTTP routing: guides/http-routing.md
-      - HTTP traffic splitting: guides/traffic-splitting.md
-      - Multiple namespaces and routes: guides/multiple-ns.md
-      - TLS: guides/tls.md
-      - TCP routing: guides/tcp.md
+    - Getting started: guides/getting-started.md
+    - Simple Gateway: guides/simple-gateway.md
+    - HTTP routing: guides/http-routing.md
+    - HTTP traffic splitting: guides/traffic-splitting.md
+    - Multiple namespaces and routes: guides/multiple-ns.md
+    - TLS: guides/tls.md
+    - TCP routing: guides/tcp.md
   - References:
-      - API specification: references/spec.md
-      - Releases: references/releases.md
-      - Implementations: references/implementations.md
+    - 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
+    - "709: Cross Namespace References from Routes": geps/gep-709.md
+    - "724: Refresh Route-Gateway Binding": geps/gep-724.md
   - Contributing:
-      - Developer guide: contributing/devguide.md
-      - Gateway Enhancement Proposal: contributing/gep.md
-      - Enhancement requests: contributing/enhancement-requests.md
-      - Community: contributing/community.md
+    - Developer guide: contributing/devguide.md
+    - Gateway Enhancement Proposal: contributing/gep.md
+    - Enhancement requests: contributing/enhancement-requests.md
+    - Community: contributing/community.md
   - FAQ: faq.md
 

site-src/geps/gep-724.md

@@ -50,6 +50,11 @@ makes it easy to accidentally expose applications (see
 
 ## Proposed Changes
 
+Although the API changes proposed here are relatively small, this represents a
+larger conceptual change. Instead of Gateways selecting Routes, Routes would
+directly reference the Gateways they wanted to attach to. This pattern was
+already possible with the existing API, but not clearly documented.
+
 One of the key concepts in the [cross-namespace references from Routes
 GEP](/geps/gep-709.md) was that of a handshake for references that cross
 namespace boundaries. A key part of that handshake was that one direction
@@ -102,6 +107,67 @@ spec:
     - path: /bar
 ```
 
+## Rationale
+
+#### 1. Remove Complexity While Possible
+A goal of v1alpha2 is to make any breaking changes we think we'll need to for
+the lifetime of the API. After this release, we plan to provide a fully
+convertible, and hopefully also fully backwards compatible, API. If we really
+do need more advanced functionality in the future, it will be fairly
+straightforward to add in a future release. On the other hand, it will be near
+impossible to remove this complexity post-v1alpha2 if we were to leave it as is.
+
+#### 2. Route Selection Added Confusion and Did Not Enhance Security
+Although it was easy to look at the selector from Gateway -> Route as providing
+Gateway admins some form of control over the Routes attached to their Gateway,
+it was nothing but security theater. Route owners still had ultimate control by
+deciding how their Routes were labeled. This also made it difficult to document
+how Gateway and Route owners should interact. One possible explanation was that
+Gateway owners should provide Route owners with a set of labels that they should
+add to their Route to bind to a given Gateway. At that point, we were still
+ultimately relying on Route owners to attach a Route to a Gateway, just making
+it a rather clunky process.
+
+It should be noted that this proposal does still retain the ability for Gateways
+to restrict the namespaces they trust Routes to attach from. This was the only
+real control Gateway admins had before this proposed change.
+
+#### 3. The Existing Defaults Were Too Permissive
+One of the common complaints about the existing API was that the defaults made
+it far too easy to accidentally expose a Route. By default, a Gateway would be
+bound to all Routes in the same namespace. Although that made the getting
+started guide simple, it would inevitably lead to some unfortunate mistakes in
+the future. As we've already learned with Kubernetes, it's very difficult to
+recover from insecure defaults. Instead, it's much safer to start with more
+explicit configuration that demonstrates clear intent to connect resources.
+
+#### 4. We Need to Support non-Gateway Route Parents
+With the expansion of this API, it's clear that a Route may have non-Gateway
+parents. This may be other Routes, mesh implementations, or custom Gateways.
+Although none of these concepts are well specified at this point, making this
+change now will give us more flexibility in the future.
+
+#### 5. Users Want Control over the Gateways Their Routes Are Attached To
+Initial feedback we've received has shown that users want to have very clear
+control over the Gateways their Routes are attached to. Even in the case of
+Gateway replacement, many Route owners would prefer to be involved in the
+process.
+
+As we get more feedback and usage of the API, we may identify more users that
+are interested in the more advanced capabilities that some form of selection may
+enable, but at this point it's clear that a large portion of users value an
+explicit way to attach a Route to a Gateway.
+
+#### 6. We Need to Maintain a Handshake Between Gateways and Routes
+Of course we do still need a handshake that will enable cross-namespace
+references between Routes and Gateways. This proposal leaves in the core
+capabilities of the v1alpha1 API for this. Gateways can specify the namespaces
+they trust Routes to bind from, and Routes directly reference the Gateways they
+want to attach to. This is largely similar to the ReferencePolicy model proposed
+for Route->Service references, but is embedded within the Route and Gateway
+resources. The alternatives below explore what this could look like with
+ReferencePolicy.
+
 ## API Changes
 
 The proposed changes here can be summarized as: