document Linkerd and Gateway HTTPRoute API groups (linkerd#1667)

As of Linkerd 2.14, we now support HTTPRoutes with both the
`policy.linkerd.io` and `gateway.networking.k8s.io` API groups. This
branch adds documentation discussing the differences between these two
API groups, and notes in the docs stating that both are supported.

linkerd.io/content/2-edge/features/httproute.md

@@ -9,6 +9,21 @@ aliases = [
 To configure routing behavior and policy for HTTP traffic, Linkerd supports the
 [HTTPRoute resource], defined by the Kubernetes [Gateway API].
 
+{{< note >}}
+Two versions of the HTTPRoute resource may be used with Linkerd:
+
+- The upstream version provided by the Gateway API, with the
+  `gateway.networking.k8s.io` API group
+- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API
+  group
+
+The two HTTPRoute resource definitions are similar, but the Linkerd version
+implements experimental features not yet available with the upstream Gateway API
+resource definition. See [the HTTPRoute reference
+documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes)
+for details.
+{{< /note >}}
+
 An HTTPRoute is a Kubernetes resource which attaches to a parent resource, such
 as a [Service]. The HTTPRoute defines a set of rules which match HTTP requests
 to that resource, based on parameters such as the request's path, method, and
@@ -44,12 +59,8 @@ exists.
 
 To get started with HTTPRoutes, you can:
 
-<!-- TODO(eliza): add this link once the fault injection doc discusses
-  HTTPRoutes...
 - [Configure fault injection](../../tasks/fault-injection/) using an outbound
   HTTPRoute.
--->
-
 - [Configure timeouts][timeouts] using an outbound HTTPRoute.
 - [Configure dynamic request routing][dyn-routing] using an outbound HTTPRoute.
 - [Configure per-route authorization policy][auth-policy] using an inbound

linkerd.io/content/2-edge/features/retries-and-timeouts.md

@@ -15,7 +15,7 @@ number of times, it becomes important to limit the total amount of time a client
 waits before giving up entirely. Imagine a number of retries forcing a client
 to wait for 10 seconds.
 
-Timeouts can be configured using either the [HTTPRoute] or[ServiceProfile]
+Timeouts can be configured using either the [HTTPRoute] or [ServiceProfile]
 resources. Currently, retries can only be configured using [ServiceProfile]s,
 but support for configuring retries using [HTTPRoutes] will be added in a future
 release. Creating these policy resources will cause the Linkerd proxy to perform

linkerd.io/content/2-edge/reference/authorization-policy.md

@@ -152,6 +152,21 @@ precendence](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking
 
 Please refer to HTTPRoute's full [spec](../httproute/).
 
+{{< note >}}
+Two versions of the HTTPRoute resource may be used with Linkerd:
+
+- The upstream version provided by the Gateway API, with the
+  `gateway.networking.k8s.io` API group
+- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API
+  group
+
+The two HTTPRoute resource definitions are similar, but the Linkerd version
+implements experimental features not yet available with the upstream Gateway API
+resource definition. See [the HTTPRoute reference
+documentation](../httproute/#linkerd-and-gateway-api-httproutes)
+for details.
+{{< /note >}}
+
 ## AuthorizationPolicy
 
 An AuthorizationPolicy provides a way to authorize traffic to a [Server] or an

linkerd.io/content/2-edge/reference/httproute.md

@@ -3,6 +3,25 @@ title = "HTTPRoute"
 description = "Reference guide to HTTPRoute resources."
 +++
 
+## Linkerd and Gateway API HTTPRoutes
+
+The HTTPRoute resource was originally specified by the Kubernetes [Gateway API]
+project. Linkerd currently supports two versions of the HTTPRoute resource: the
+upstream version from the Gateway API, with the
+`gateway.networking.kubernetes.io` API group, and a Linkerd-specific version,
+with the `policy.linkerd.io` API group. While these two resource definitions are
+largely the same, the `policy.linkerd.io` HTTPRoute resource is an experimental
+version that contains features not yet stabilized in the upstream
+`gateway.networking.k8s.io` HTTPRoute resource, such as
+[timeouts](#httproutetimeouts). Both the Linkerd and Gateway API resource
+definitions may coexist within the same cluster, and both can be used to
+configure policies for use with Linkerd.
+
+This documentation describes the `policy.linkerd.io` HTTPRoute resource. For a
+similar description of the upstream Gateway API HTTPRoute resource, refer to the
+Gateway API's [HTTPRoute
+specification](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute).
+
 ## HTTPRoute Spec
 
 An HTTPRoute spec may contain the following top level fields:
@@ -287,4 +306,5 @@ spec:
 ```
 
 [ServiceProfile]: ../../features/service-profiles/
+[Gateway API]: https://gateway-api.sigs.k8s.io/
 [GEP-1426]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries

linkerd.io/content/2-edge/tasks/configuring-dynamic-request-routing.md

@@ -104,6 +104,21 @@ spec:
 EOF
 ```
 
+{{< note >}}
+Two versions of the HTTPRoute resource may be used with Linkerd:
+
+- The upstream version provided by the Gateway API, with the
+  `gateway.networking.k8s.io` API group
+- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API
+  group
+
+The two HTTPRoute resource definitions are similar, but the Linkerd version
+implements experimental features not yet available with the upstream Gateway API
+resource definition. See [the HTTPRoute reference
+documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes)
+for details.
+{{< /note >}}
+
 In `parentRefs` we specify the resources we want this [`HTTPRoute`] instance to
 act on. So here we point to the `backend-a-podinfo` Service on the [`HTTPRoute`]'s
 namespace (`test`), and also specify the Service port number (not the Service's

linkerd.io/content/2-edge/tasks/configuring-per-route-policy.md

@@ -181,6 +181,21 @@ spec:
 EOF
 ```
 
+{{< note >}}
+Two versions of the HTTPRoute resource may be used with Linkerd:
+
+- The upstream version provided by the Gateway API, with the
+  `gateway.networking.k8s.io` API group
+- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API
+  group
+
+The two HTTPRoute resource definitions are similar, but the Linkerd version
+implements experimental features not yet available with the upstream Gateway API
+resource definition. See [the HTTPRoute reference
+documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes)
+for details.
+{{< /note >}}
+
 This will create an [`HTTPRoute`] targeting the `authors-server` [`Server`] resource
 we defined previously. The `rules` section defines a list of matches, which
 determine which requests match the [`HTTPRoute`]. Here, we 've defined a match

linkerd.io/content/2-edge/tasks/configuring-timeouts.md

@@ -31,6 +31,10 @@ HTTPRoute resources with the `policy.linkerd.io` API group, *not* the
 When the [GEP-1742](https://gateway-api.sigs.k8s.io/geps/gep-1742/) timeout
 fields are added to the upstream resource definition, Linkerd will support
 timeout configuration for HTTPRoutes with both API groups.
+
+See [the HTTPRoute reference
+documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes)
+for details on the two versions of the HTTPRoute resource.
 {{< /warning >}}
 
 Each [rule](../../reference/httproute/#httprouterule) in an [HTTPRoute] may

linkerd.io/content/2-edge/tasks/fault-injection.md

@@ -165,6 +165,21 @@ spec:
 EOF
 ```
 
+{{< note >}}
+Two versions of the HTTPRoute resource may be used with Linkerd:
+
+- The upstream version provided by the Gateway API, with the
+  `gateway.networking.k8s.io` API group
+- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API
+  group
+
+The two HTTPRoute resource definitions are similar, but the Linkerd version
+implements experimental features not yet available with the upstream Gateway API
+resource definition. See [the HTTPRoute reference
+documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes)
+for details.
+{{< /note >}}
+
 When Linkerd sees traffic going to the `books` service, it will send 9/10
 requests to the original service and 1/10 to the error injector. You can see
 what this looks like by running `stat` and filtering explicitly to just the