add top-level HTTPRoute features doc (#1657)

Currently, the website doesn't really have a top-level summary of what
the HTTPRoute resource is and what it can do, similar to the
ServiceProfiles feature page. I thought this would be useful to add, as
it can be used for other documentation to link to, and will also be
useful as a place to collect all the documentation on things users can
do using HTTPRoutes. In addition, we can also add stuff about GAMMA
support and about the difference between `policy.linkerd.io` and
`gateway.networking.kubernetes.io` HTTPRoutes here, as well.

I've also updated some of the other documentation that mentions the
HTTPRoute resource to link to this page.

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

@@ -0,0 +1,64 @@
++++
+title = "HTTPRoutes"
+description = "Linkerd can use the HTTPRoute resource to configure per-route policies."
+aliases = [
+  "../httproutes/"
+]
++++
+
+To configure routing behavior and policy for HTTP traffic, Linkerd supports the
+[HTTPRoute resource], defined by the Kubernetes [Gateway API].
+
+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
+headers, and can configure how requests matching that rule are routed by the
+Linkerd service mesh.
+
+Two types of HTTPRoute are used for configuring the behavior of Linkerd's
+proxies:
+
+- HTTPRoutes with a [Service] as their parent resource configure policies for
+  _outbound_ proxies in pods which are clients of that [Service]. Outbound
+  policy includes [dynamic request routing][dyn-routing], adding request
+  headers, modifying a request's path, and reliability features such as
+  [timeouts].
+- HTTPRoutes with a [Server] as their parent resource configure policy for
+  _inbound_ proxies in pods which recieve traffic to that [Server]. Inbound
+  HTTPRoutes are used to configure fine-grained [per-route authorization and
+  authentication policies][auth-policy].
+
+{{< warning >}}
+**Outbound HTTPRoutes and [ServiceProfile](../service-profiles/)s provide
+overlapping configuration.** For backwards-compatibility reasons, a
+ServiceProfile will take precedence over HTTPRoutes which configure the same
+Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute,
+proxies will use the ServiceProfile configuration, rather than the HTTPRoute
+configuration, as long as the ServiceProfile
+exists.
+{{< /warning >}}
+
+To get started with HTTPRoutes, you can:
+
+<!-- TODO(eliza): add this link once the timeout doc discusses HTTPRoutes...
+- [Configure timeouts][timeouts] using an outbound HTTPRoute.
+-->
+<!-- TODO(eliza): add this link once the fault injection doc discusses
+  HTTPRoutes...
+- [Configure fault injection](../../tasks/fault-injection/) using an outbound
+  HTTPRoute.
+-->
+
+- [Configure dynamic request routing][dyn-routing] using an outbound HTTPRoute.
+- [Configure per-route authorization policy][auth-policy] using an inbound
+  HTTPRoute.
+- See the [reference documentation](../../reference/httproute/) for a complete
+  description of the HTTPRoute resource.
+
+[HTTPRoute resource]: https://gateway-api.sigs.k8s.io/api-types/httproute/
+[Gateway API]: https://gateway-api.sigs.k8s.io/
+[Service]: https://kubernetes.io/docs/concepts/services-networking/service/
+[Server]: ../../reference/authorization-policy/#server
+[auth-policy]: ../../tasks/configuring-per-route-policy/
+[dyn-routing]:../../tasks/configuring-dynamic-request-routing/
+[timeouts]: ../../tasks/configuring-dynamic-request-routing/

linkerd.io/content/2-edge/features/server-policy.md

@@ -70,8 +70,8 @@ the fly.
 Two policy CRDs represent "targets" for policy: subsets of traffic over which
 policy can be applied.
 
-- `Server`: all traffic to a port, for a set of pods in a namespace
-- `HTTPRoute`: a subset of HTTP requests for a `Server`
+- [`Server`]: all traffic to a port, for a set of pods in a namespace
+- [`HTTPRoute`]: a subset of HTTP requests for a [`Server`]
 
 Two policy CRDs represent authentication rules that must be satisfied as part of
 a policy rule:
@@ -87,11 +87,11 @@ authentication rules to targets.
   unless an authentication rule is met
 
 - `ServerAuthorization`: an earlier form of policy that restricts access to
-  `Servers` only (i.e. not `HTTPRoutes`)
+  [`Server`]s only (i.e. not [`HTTPRoute`]s)
 
 The general pattern for Linkerd's dynamic, fine-grained policy is to define the
 traffic target that must be protected (via a combination of `Server` and
-`HTTPRoute` CRs); define the types of authentication that are required before
+[`HTTPRoute`] CRs); define the types of authentication that are required before
 access to that traffic is permitted (via `MeshTLSAuthentication` and
 `NetworkAuthentication`); and then define the policy that maps authentication to
 target (via an `AuthorizationPolicy`).
@@ -102,7 +102,7 @@ details on how these resources work.
 ## ServerAuthorization vs AuthorizationPolicy
 
 Linkerd 2.12 introduced `AuthorizationPolicy` as a more flexible alternative to
-`ServerAuthorization` that can target `HTTPRoute`s as well as `Server`s. Use of
+`ServerAuthorization` that can target [`HTTPRoute`]s as well as `Server`s. Use of
 `AuthorizationPolicy` is preferred, and `ServerAuthorization` will be deprecated
 in future releases.
 
@@ -113,9 +113,9 @@ from Kubernetes, meaning that the pod would not be able to start. Thus, any
 default-deny setup must, in practice, still authorize these probes.
 
 In order to simplify default-deny setups, Linkerd automatically authorizes
-probes to pods. These default authorizations apply only when no `Server` is
-configured for a port, or when a `Server` is configured but no `HTTPRoutes` are
-configured for that `Server`. If any `HTTPRoute` matches the `Server`, these
+probes to pods. These default authorizations apply only when no [`Server`] is
+configured for a port, or when a [`Server`] is configured but no [`HTTPRoute`]s are
+configured for that [`Server`]. If any [`HTTPRoute`] matches the `Server`, these
 automatic authorizations are not created and you must explicitly create them for
 health and readiness probes.
 
@@ -132,3 +132,6 @@ result in an abrupt termination of those connections.
 
 - [Policy reference](../../reference/authorization-policy/)
 - [Guide to configuring per-route policy](../../tasks/configuring-per-route-policy/)
+
+[`HTTPRoute`]: ../httproute/
+[`Server`]: ../../reference/authorization-policy/#server

linkerd.io/content/2-edge/reference/proxy-metrics.md

@@ -258,10 +258,10 @@ Kubernetes resources to which traffic is routed by the proxy:
 
 * `parent_group`, `parent_kind`, `parent_name`, and `parent_namespace` reference
   the parent resource through which the proxy discovered the route binding.
-  The parent resource of an HTTPRoute is generally a Service.
+  The parent resource of an [HTTPRoute] is generally a Service.
 * `route_group`, `route_kind`, `route_name`, and `route_namespace` reference the
   route resource through which the proxy discovered the route binding. This will
-  either reference an HTTPRoute resource or a default (synthesized) route.
+  either reference an [HTTPRoute] resource or a default (synthesized) route.
 * `backend_group`, `backend_kind`, `backend_name`, and `backend_namespace`
   reference the backend resource to which which the proxy routed the request.
   This will always be a Service.
@@ -280,3 +280,4 @@ following labels:
 [prom-format]: https://prometheus.io/docs/instrumenting/exposition_formats/#format-version-0.0.4
 [pod-template-hash]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
+[HTTPRoute]: ../../features/httproute/

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

@@ -75,7 +75,7 @@ PODINFO_UI_MESSAGE=A backend
 
 ## Introducing HTTPRoute
 
-Let's apply the following `HTTPRoute` resource to enable header-based routing:
+Let's apply the following [`HTTPRoute`] resource to enable header-based routing:
 
 ```yaml
 cat <<EOF | kubectl -n test apply -f -
@@ -104,16 +104,16 @@ spec:
 EOF
 ```
 
-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
+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
 target port).
 
 {{< warning >}}
 Outbound `HTTPRoute`s are **incompatible with `ServiceProfiles`**. If a
 [ServiceProfile](../../features/service-profiles/) is defined for the parent
-Service of an `HTTPRoute`, proxies will use the `ServiceProfile` configuration,
-rather than the `HTTPRoute` configuration, as long as the `ServiceProfile`
+Service of an [`HTTPRoute`], proxies will use the `ServiceProfile` configuration,
+rather than the [`HTTPRoute`] configuration, as long as the `ServiceProfile`
 exists.
 {{< /warning >}}
 
@@ -169,3 +169,5 @@ request (the frontend pod in this case) and so that pod needs to be injected,
 whereas the destination pods don't require to be injected. But of course the
 more workloads you have injected the better, to benefit from things like easy
 mTLS setup and all the other advantages that linkerd brings to the table!
+
+[`HTTPRoute`]: ../../features/httproute/

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

@@ -1,5 +1,5 @@
 +++
-title = "Configuring Per-Route Policy"
+title = "Configuring Per-Route Authorization Policy"
 description = "Fine-grained authorization policies can be configured for individual HTTP routes."
 aliases = []
 +++

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

@@ -14,9 +14,9 @@ in the [service profile](../../features/service-profiles/) for the service you'r
 sending requests to.
 
 {{< note >}}
-Routes configured in service profiles are different from HTTPRoute resources.
+Routes configured in service profiles are different from [HTTPRoute] resources.
 Service profile routes allow you to collect per-route metrics and configure
-client-side behavior such as retries and timeouts. HTTPRoute resources, on the
+client-side behavior such as retries and timeouts. [HTTPRoute] resources, on the
 other hand, can be the target of AuthorizationPolicies and allow you to specify
 per-route authorization.
 {{< /note >}}
@@ -87,3 +87,5 @@ are enabled.  Since an original request may fail the first time, but a retry of
 that request might succeed, the effective success rate is usually ([but not
 always](../configuring-timeouts/#monitoring-timeouts)) higher than the
 actual success rate.
+
+[HTTPRoute]: ../../features/httproute/

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

@@ -4,17 +4,11 @@ description = "Configure Linkerd to automatically fail requests that take too lo
 +++
 
 To limit how long Linkerd will wait before failing an outgoing request to
-another service, you can configure timeouts. These work by adding a little bit
-of extra information to the [service profile](../../features/service-profiles/) for
+another service, you can configure timeouts. Timeouts can be specified using
+either [HTTPRoute]s or [service profile](../../features/service-profiles/) for
 the service you're sending requests to.
 
-{{< note >}}
-Routes configured in service profiles are different from HTTPRoute resources.
-Service profile routes allow you to collect per-route metrics and configure
-client-side behavior such as retries and timeouts. HTTPRoute resources, on the
-other hand, can be the target of AuthorizationPolicies and allow you to specify
-per-route authorization.
-{{< /note >}}
+## Using ServiceProfiles
 
 Each route may define a timeout which specifies the maximum amount of time to
 wait for a response (including retries) to complete after the request is sent.

linkerd.io/content/2-edge/tasks/getting-per-route-metrics.md

@@ -12,9 +12,9 @@ For a tutorial that shows this functionality off, check out the
 [books demo](../books/#service-profiles).
 
 {{< note >}}
-Routes configured in service profiles are different from HTTPRoute resources.
+Routes configured in service profiles are different from [HTTPRoute] resources.
 Service profile routes allow you to collect per-route metrics and configure
-client-side behavior such as retries and timeouts. HTTPRoute resources, on the
+client-side behavior such as retries and timeouts. [HTTPRoute] resources, on the
 other hand, can be the target of AuthorizationPolicies and allow you to specify
 per-route authorization.
 {{< /note >}}
@@ -99,3 +99,5 @@ This will select only the requests observed and show the `:authority` and
   attention to `rt_route`. If it is missing entirely, compare the `:path` to
   the regex you'd like for it to match, and use a
   [tester](https://regex101.com/) with the Golang flavor of regex.
+
+[HTTPRoute]: ../../features/httproute/

linkerd.io/content/2-edge/tasks/traffic-shifting.md

@@ -11,7 +11,7 @@ implement A/B experiments, red/green deploys, canary rollouts,
 Linkerd supports two different ways to configure traffic shifting: you can
 use the [Linkerd SMI extension](../linkerd-smi/) and
 [TrafficSplit](https://github.com/servicemeshinterface/smi-spec/blob/main/apis/traffic-split/v1alpha2/traffic-split.md/)
-resources, or you can use [HTTPRoute](../../reference/httproute/) resources which
+resources, or you can use [HTTPRoute](../../features/httproute/) resources which
 Linkerd natively supports. While certain integrations such as
 [Flagger](../flagger/) rely on the SMI and `TrafficSplit` approach, using
 `HTTPRoute` is the preferred method going forward.