Documenting Route attachment for v1alpha2

site-src/v1alpha2/concepts/api-overview.md

@@ -17,9 +17,10 @@ section in the Security model for details.
 
 ## Resource model
 
-> Note: Resources will initially live in the `gateway.networking.k8s.io` API group as
-> Custom Resource Definitions (CRDs). Unqualified resource names will implicitly
-> be in this API group.
+!!! note
+  Gateway API Resources live in the `gateway.networking.k8s.io` API group as
+  Custom Resource Definitions (CRDs). Unqualified resource names will implicitly
+  be in this API group.
 
 There are three main types of objects in our resource model:
 
@@ -67,41 +68,43 @@ GatewayClass.
 
 As the Gateway spec captures user intent, it may not contain a complete
 specification for all attributes in the spec. For example, the user may omit
-fields such as addresses, TLS settings. This allows the controller
-managing the GatewayClass to provide these settings for the user, resulting in a
-more portable spec. This behaviour will be made clear using the GatewayClass
-Status object.
+fields such as addresses, TLS settings. This allows the controller managing the
+GatewayClass to provide these settings for the user, resulting in a more
+portable spec. This behaviour will be made clear using the GatewayClass Status
+object.
 
-A Gateway MAY contain one or more *Route references which serve to direct
-traffic for a subset of traffic to a specific service.*
-
-### {HTTP,TCP,Foo}Route
+### Routes
 
 Route objects define protocol-specific rules for mapping requests from a Gateway
-to Kubernetes Services.
+to Kubernetes Services. There are 4 Route resources included with the Gateway
+API:
+
+* HTTPRoute
+* TCPRoute
+* TLSRoute
+* UDPRoute
 
-`HTTPRoute` and `TCPRoute` are currently the only defined Route objects.
-Additional protocol-specific Route objects may be added in the future.
+Additional Route resources may be added in the future.
 
-### Route binding
+## Attaching Routes to Gateways
 
-When a Route binds to a Gateway it represents configuration that is applied on
-the Gateway that configures the underlying load balancer or proxy. How and which
-Routes bind to Gateways is controlled by the resources themselves. Route and
-Gateway resources have built-in controls to permit or constrain how they select
-each other. This is useful for enforcing organizational policies for how Routes
+When a Route attaches to a Gateway it represents configuration that is applied
+on the Gateway that configures the underlying load balancer or proxy. How and
+which Routes bind to Gateways is controlled by the resources themselves. Route
+and Gateway resources have built-in controls to permit or constrain how they are
+attached. This is useful for enforcing organizational policies for how Routes
 are exposed and on which Gateways. Consider the following example:
 
 > A Kubernetes cluster admin has deployed a Gateway “shared-gw” in the “Infra”
 > Namespace to be used by different application teams for exposing their
 > applications outside the cluster. Teams A and B (in Namespaces “A” and “B”
-> respectively) bind their Routes to this Gateway. They are unaware of each other
-> and as long as their Route rules do not conflict with each other they can
-> continue operating in isolation. Team C has special networking needs (perhaps
-> performance, security, or criticality) and they need a dedicated Gateway to
-> proxy their application to the outside world. Team C deploys their own Gateway
-> “dedicated-gw”  in the “C” Namespace that can only be used by apps in the "C"
-> Namespace.
+> respectively) bind their Routes to this Gateway. They are unaware of each
+> other and as long as their Route rules do not conflict with each other they
+> can continue operating in isolation. Team C has special networking needs
+> (perhaps performance, security, or criticality) and they need a dedicated
+> Gateway to proxy their application to the outside world. Team C deploys their
+> own Gateway“dedicated-gw”  in the “C” Namespace that can only be used by apps
+> in the "C" Namespace.
 
 <!-- source: https://docs.google.com/presentation/d/1neBkFDTZ__vRoDXIWvAcxk2Pb7-evdBT6ykw_frf9QQ/edit?usp=sharing -->
 ![route binding](/images/gateway-route-binding.png)
@@ -119,96 +122,32 @@ different relationships that Gateways and Routes can have:
   a single Route to control application exposure simultaneously across different
   IPs, load balancers, or networks.
 
-*In summary, Gateways select Routes and Routes control their exposure. When a
-Gateway selects a Route that allows itself to be exposed, then the Route will
-bind to the Gateway. When Routes are bound to a Gateway it means their
-collective routing rules are configured on the underlying load balancers or
-proxies that are managed by that Gateway. Thus, a Gateway is a logical
-representation of a networking data plane that can be configured through
-Routes.*
-
-#### Route Selection
-
-A Gateway selects routes based on the Route metadata, specifically the kind,
-namespace, and labels of Route resources. Routes are actually bound to specific
-listeners within the Gateway so each listener has a `listener.routes` field
-which selects Routes by one or more of the following criterea:
-
-- **Label** - A Gateway can select Routes via labels that exist on the
-resource (similar to how Services select Pods via Pod labels).
-- **Kind** - A Gateway listener can only select a single type of Route
-resource. This could be an HTTPRoute, TCPRoute, or a custom Route type.
-- **Namespace** - A Gateway can also control from which Namespaces Routes can be
-selected via the `namespaces.from` field. It supports three possible values:
-    - `SameNamespace` is the default option. Only Routes in the same namespace
-      as this Gateway will be selected.
-    - `All` will select Routes from all Namespaces.
-    - `Selector` means that Routes from a subset of Namespaces selected by a
-      Namespace label selector will be selected by this Gateway. When `Selector`
-      is used then the `listeners.routes.namespaces.selector` field can be used
-      to specify label selectors. This field is not supported with `All` or
+### How it Works
+
+The following is required for a Route to be attached to a Gateway:
+
+1. The Route needs an entry in its `parentRefs` field referencing the Gateway.
+2. At least one listener on the Gateway needs to allow this attachment.
+
+Each Gateway listener can restrict which Routes can be attached with the
+following mechanisms:
+
+1. **Hostname:** When the `hostname` field on a listener is set, attached Routes
+   that specify a `hostnames` field must have at least one overlapping value.
+2. **Namespaces:** The `namespaces` field on a listener can be used to restrict
+   where Routes may be attached from. The `namespaces.from` field supports the
+   following values:
+    * `SameNamespace` is the default option. Only Routes in the same namespace
+      as this Gateway may be attached.
+    * `All` will allow Routes from all Namespaces to be attached.
+    * `Selector` means that Routes from a subset of Namespaces selected by a
+      Namespace label selector may be attached to this Gateway. When `Selector`
+      is used, the `listeners.routes.namespaces.selector` field must be used to
+      specify label selectors. This field is not supported with `All` or
       `SameNamespace`.
 
-The below Gateway will select all HTTPRoute resources with the `expose:
-prod-web-gw` across all Namespaces in the cluster.
-
-```
-kind: Gateway
-...
-spec:
-  listeners:
-  - routes:
-      kind: HTTPRoute
-      selector:
-        matchLabels:
-          expose: prod-web-gw
-      namespaces:
-        from: All
-```
-
-#### Route Exposure
-
-Routes can determine how they are exposed through Gateways. The `gateways.allow`
-field supports three values:
-
-- `All` is the default value if none is specified. This leaves all binding
-to the Route label and Namespace selectors on the Gateway.
-- `SameNamespace` only allows this Route to bind with Gateways from the
-same Namespace.
-- `FromList` allows an explicit list of Gateways to be specifiied that a
-Route will bind with. `gateways.gatewayRefs` is only supported with this option.
-
-The following `my-route` Route selects only the `foo-gateway` in the
-`foo-namespace` and will not be able to bind with any other Gateways. Note that
-`foo-gateway` is in a different Namespace. If the `foo-gateway` allows
-cross-Namespace binding and also selects this Route then `my-route` will bind to
-it.
-
-```yaml
-kind: HTTPRoute
-metadata:
-  name: my-route
-  namespace: bar-namespace
-spec:
-  gateways:
-    allow: FromList
-    gatewayRefs:
-    - name: foo-gateway
-      namespace: foo-namespace
-```
-
-Note that Gateway and Route binding is bi-directional. This means that both
-resources must select each other for them to bind. If a Gateway has Route label
-selectors that do not match any existing Route then nothing will bind to it even
-if a Route's `spec.gateways.allow = All`. Similarly, if a Route references a
-specific Gateway, but that Gateway is not selecting the Route's Namespace, then
-they will not bind. A binding will only take place if both resources select each
-other.
-
-It may not always be apparent from the resource specifications which Gateways
-and Routes are bound, but binding can be determined from the resource status.
-The [Route status](/api-types/httproute#routestatus) will list all of the Gateways that
-a Route is bound to and any relevant conditions for the binding.
+If none of the above are specified, a Gateway listener will trust Routes
+attached from the same namespace that support the listener protocol.
 
 ### Combined types
 

site-src/v1alpha2/concepts/security-model.md

@@ -96,14 +96,11 @@ configuration](https://github.com/open-policy-agent/gatekeeper-library/pull/24)
 that could be used for this.
 
 ## Route Namespaces
-Gateway API allow Gateways to select Routes across multiple Namespaces.
+Gateway API enables Routes to be attached to Gateways from different Namespaces.
 Although this can be remarkably powerful, this capability needs to be used
-carefully. Gateways include a `RouteNamespaces` field that allows selecting
-multiple namespaces with a label selector. By default, this is limited to Routes
-in the same namespace as the Gateway. Additionally, Routes include a `Gateways`
-field that allows them to restrict which Gateways use them. If the Gateways
-field is not specified (i.e. its empty), then the Route will default to allowing
-selection by Gateways in the same namespace.
+carefully. Gateway Listeners include a `namespaces` field that can allow Routes
+to be attached from additional namespaces. By default, this is limited to Routes
+in the same namespace as the Gateway.
 
 ## Controller Requirements
 To be considered conformant with the Gateway API spec, controllers need to: