Merge pull request #1082 from cxhiano/1021-doc

Provide more details on route parentRef in documentation for routes <> Gateways attachment.

Author: k8s-ci-robot

site-src/concepts/api-overview.md

@@ -171,6 +171,31 @@ 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.
 
+#### Referencing Gateways
+
+!!! info "Experimental Channel"
+
+    The `Port` field described below is currently only included in the
+    "Experimental" channel of Gateway API. For more information on release
+    channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning/#adding-experimental-fields).
+
+A Route can reference a Gateway by specifying the namespace (optional if the
+Route and the Gateway are in the same namespace) and name of the Gateway in
+a `parentRef`. A Route can further select a subset of listeners under the
+Gateway using the following fields in `parentRef`:
+
+1. **SectionName** When `sectionName` is set, the Route selects the listener
+   with the specified name.
+2. **Port** When `port` is set, the Route selects all listeners listening on
+   the specified port and with protocol compatible with this kind of Route.
+
+When multiple fields in `parentRef` are set, the Route selects listeners that
+satisfy all conditions specified in those fields. For example, when both
+`sectionName` and `port` are set, the Route selects listeners with the specified
+name AND listening on the specified port.
+
+#### Restricting Route Attachment
+
 Each Gateway listener can restrict which Routes can be attached with the
 following mechanisms: