From c20ba93a26d200a1e0292d6b3800c3f46e264890 Mon Sep 17 00:00:00 2001
From: Shane Utt <shaneutt@linux.com>
Date: Mon, 23 Aug 2021 10:35:45 -0400
Subject: [PATCH] docs: update tcp guide for v1alpha2

---
 examples/v1alpha2/basic-tcp.yaml | 45 +++++++++++++++++++++++
 site-src/v1alpha2/guides/tcp.md  | 63 +++++++++++++++++++++++---------
 2 files changed, 91 insertions(+), 17 deletions(-)
 create mode 100644 examples/v1alpha2/basic-tcp.yaml

diff --git a/examples/v1alpha2/basic-tcp.yaml b/examples/v1alpha2/basic-tcp.yaml
new file mode 100644
index 0000000000..779914e742
--- /dev/null
+++ b/examples/v1alpha2/basic-tcp.yaml
@@ -0,0 +1,45 @@
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: Gateway
+metadata:
+  name: my-tcp-gateway
+spec:
+  gatewayClassName: my-tcp-gateway-class
+  listeners:
+  - name: foo
+    protocol: TCP
+    port: 8080
+    routes:
+      kinds:
+      - kind: TCPRoute
+  - name: bar
+    protocol: TCP
+    port: 8090
+    routes:
+      kinds:
+      - kind: TCPRoute
+---
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: TCPRoute
+metadata:
+  name: tcp-app-1
+spec:
+  parentRefs:
+  - name: my-tcp-gateway
+    sectionName: foo
+  rules:
+  - backendRefs:
+    - name: my-foo-service
+      port: 6000
+---
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: TCPRoute
+metadata:
+  name: tcp-app-2
+spec:
+  parentRefs:
+  - name: my-tcp-gateway
+    sectionName: bar
+  rules:
+  - backendRefs:
+    - name: my-bar-service
+      port: 6000
diff --git a/site-src/v1alpha2/guides/tcp.md b/site-src/v1alpha2/guides/tcp.md
index 96f6032f4f..42891a88f6 100644
--- a/site-src/v1alpha2/guides/tcp.md
+++ b/site-src/v1alpha2/guides/tcp.md
@@ -1,10 +1,5 @@
-
-!!! danger
-    This page has not been updated for v1alpha2 yet.
-
-Gateway API is designed to work with multiple protocols.
-[TCPRoute](/v1alpha2/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) is one such route which
-allows for managing TCP traffic.
+Gateway API is designed to work with multiple protocols and [TCPRoute][tcproute]
+is one such route which allows for managing [TCP][tcp] traffic.
 
 In this example, we have one Gateway resource and two TCPRoute resources that
 distribute the traffic with the following rules:
@@ -14,17 +9,51 @@ distribute the traffic with the following rules:
 - All TCP streams on port 8090 of the Gateway are forwarded to port 6000 of
   `my-bar-service` Kubernetes Service.
 
-Please note the following:
+In this example two `TCP` listeners will be applied to the [Gateway][gateway]
+in order to route them to two separate backend `TCPRoutes`, note that the
+`protocol` set for the `listeners` on the `Gateway` is `TCP`:
+
+```
+{% include 'v1alpha2/basic-tcp.yaml' %}
+```
 
-- The `protocol` of listeners on the Gateway is `TCP`.
-- Each listener selects exactly one TCPRoute. This is important since the routing
-  decision is performed based on destination port only. If more metadata is used
-  for routing decisions, then one may associate multiple TCPRoutes to a single
-  Gateway listener. Implementations can support such use-cases by adding a custom
-  resource to specify advanced routing properties and then referencing it in
-  `spec.rules[].matches[].extensionRef`. Conflicts due to routing colisions should
-  be resolved as per the [conflict resolution](/v1alpha2/concepts/guidelines#conflicts) guidelines.
+In the above example we separate the traffic for the two separate backend TCP
+[Services][svc] by using the `sectionName` field in the `parentRefs`:
 
+```yaml
+spec:
+  parentRefs:
+  - name: my-tcp-gateway
+    sectionName: foo
 ```
-{% include 'v1alpha1/basic-tcp.yaml' %}
+
+This corresponds directly with the `name` in the `listeners` in the `Gateway`:
+
+```yaml
+  listeners:
+  - name: foo
+    protocol: TCP
+    port: 8080
+  - name: bar
+    protocol: TCP
+    port: 8090
 ```
+
+In this way each `TCPRoute` "attaches" itself to a different port on the
+`Gateway` so that the service `my-foo-service` is taking traffic for port `8080`
+from outside the cluster and `my-bar-service` takes the port `8090` traffic.
+
+## Alternatives: TCP Traffic Routing Using Metadata
+
+While in the above examples we mainly focused on routing by port, it is also
+possible to use metadata to route traffic from the `Gateway` to the underlying
+`TCPRoutes` using `spec.rules[].matches[].extensionRef`.
+
+See the [spec][tcproute] for more details on how to configure alternative logic
+for routing TCP traffic beyond just using ports and selecting `listener` names.
+
+[tcproute]:/v1alpha2/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute
+[tcp]:https://datatracker.ietf.org/doc/html/rfc793
+[httproute]:/v1alpha2/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute
+[gateway]:/v1alpha2/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway
+[svc]:https://kubernetes.io/docs/concepts/services-networking/service/