clarify support for VirtualService in waypoints

.spelling

@@ -617,6 +617,7 @@ httpbin
 httpbin.foo.svc.cluster.local
 httpbin.org
 HTTPRoute
+HTTPRoutes
 HTTPS
 https
 Hu
@@ -638,6 +639,7 @@ Incrementality
 Indo-Pacific
 InferenceModel
 InferencePool
+ingress2gateway
 initContainer
 initializer
 initializers

content/en/boilerplates/gateway-api-gamma-experimental.md

@@ -7,7 +7,7 @@
 
 {{< warning >}}
 This document configures Istio using Gateway API features that are
-[experimental](https://gateway-api.sigs.k8s.io/geps/overview/#status)
+[experimental](https://gateway-api.sigs.k8s.io/concepts/versioning/#release-channels)
 Before using the Gateway API instructions, make sure to:
 
 1) Install the **experimental version** of the Gateway API CRDs:

content/en/docs/ambient/usage/add-workloads/index.md

@@ -34,14 +34,16 @@ For example, setting a `PeerAuthentication` policy with mTLS mode set to `STRICT
 
 ### Pods inside the mesh using sidecar mode
 
-Istio supports East-West interoperability between a pod with a sidecar and a pod using ambient mode, within the same mesh. The sidecar proxy knows to use the HBONE protocol since the destination has been discovered to be an HBONE destination.
-
-{{< tip >}}
-For sidecar proxies to use the HBONE/mTLS signaling option when communicating with ambient destinations, they need to be configured with `ISTIO_META_ENABLE_HBONE` set to `true` in the proxy metadata. This is the default in `MeshConfig` when using the `ambient` profile, hence you do not have to do anything else when using this profile.
-{{< /tip >}}
+When Istio is installed with the `ambient` profile, sidecar proxies gain support for the HBONE protocol.  This enables east-west interoperability between a pod with a sidecar and a pod using ambient mode, within the same mesh. The sidecar proxy knows to use the HBONE protocol since the destination has been discovered to be an HBONE destination.
 
 A `PeerAuthentication` policy with mTLS mode set to `STRICT` will allow traffic from a pod with an Istio sidecar proxy.
 
+{{< warning >}}
+Istio does not currently support waypoint discovery from sidecars. If you configure a pod in an ambient mesh to use a waypoint, and attempt to connect to that pod from an HBONE-enabled sidecar, the sidecar will ignore the instruction to use the waypoint and instead connect directly to the destination ztunnel. Depending on your configuration, this may allow you to bypass policy. Support for waypoint discovery is planned for an upcoming release.
+{{< /warning >}}
+
+For sidecar proxies to use the HBONE/mTLS signaling option when communicating with ambient destinations, they need to be configured with `ISTIO_META_ENABLE_HBONE` set to `true` in the proxy metadata. This is the default in `MeshConfig` when using the `ambient` profile.
+
 ### Ingress and egress gateways and ambient mode pods
 
 An ingress gateway may run in a non-ambient namespace, and expose services provided by ambient mode, sidecar mode or non-mesh pods. Interoperability is also supported between pods in ambient mode and Istio egress gateways.

content/en/docs/ambient/usage/l7-features/index.md

@@ -6,19 +6,15 @@ owner: istio/wg-networking-maintainers
 test: no
 ---
 
-By adding a waypoint proxy to your traffic flow you can enable more of [Istio's features](/docs/concepts). Waypoints are configured using the {{< gloss "gateway api" >}}Kubernetes Gateway API{{< /gloss >}}.
+By adding a waypoint proxy to your traffic flow you can enable more of [Istio's features](/docs/concepts). Waypoints are configured using {{< gloss "gateway api" >}}Gateway API{{< /gloss >}}.
 
 {{< warning >}}
-Usage of VirtualService with the ambient data plane mode is considered Alpha. Mixing with Gateway API configuration is not supported, and will lead to undefined behavior.
-{{< /warning >}}
-
-{{< warning >}}
-`EnvoyFilter` is Istio's break-glass API for advanced configuration of Envoy proxies. Please note that *`EnvoyFilter` is not currently supported for any existing Istio version with waypoint proxies*. While it may be possible to use `EnvoyFilter` with waypoints in limited scenarios, its use is not supported, and is actively discouraged by the maintainers. The alpha API may break in future releases as it evolves. We expect official support will be provided at a later date.
+The VirtualService and EnvoyFilter APIs are not supported in waypoints. [Read more below](/docs/ambient/usage/l7-features/#unsupported-apis-with-waypoints).
 {{< /warning >}}
 
 ## Route and policy attachment
 
-The Gateway API defines the relationship between objects (such as routes and gateways) in terms of *attachment*.
+Gateway API defines the relationship between objects (such as routes and gateways) in terms of *attachment*.
 
 * Route objects (such as [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/)) include a way to reference the **parent** resources it wants to attach to.
 * Policy objects are considered [*metaresources*](https://gateway-api.sigs.k8s.io/geps/gep-713/): objects that augments the behavior of a **target** object in a standard way.
@@ -31,10 +27,13 @@ With a waypoint proxy deployed, you can use the following traffic route types:
 
 |  Name  | Feature Status | Attachment |
 | --- | --- | --- |
-| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/guides/http-routing/) | Beta | `parentRefs` |
+| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/guides/http-routing/) | Stable | `parentRefs` |
+| [`GRPCRoute`](https://gateway-api.sigs.k8s.io/guides/grpc-routing/) | Stable | `parentRefs` |
 | [`TLSRoute`](https://gateway-api.sigs.k8s.io/guides/tls) | Alpha | `parentRefs` |
 | [`TCPRoute`](https://gateway-api.sigs.k8s.io/guides/tcp/) | Alpha | `parentRefs` |
 
+(TLS and TCP routing are stable features in Istio, but support for these objects remains at Alpha because the Gateway API objects are still in the experimental channel.)
+
 Refer to the [traffic management](/docs/tasks/traffic-management/) documentation to see the range of features that can be implemented using these routes.
 
 ## Security
@@ -43,7 +42,7 @@ Without a waypoint installed, you can only use [Layer 4 security policies](/docs
 
 |  Name  | Feature Status | Attachment |
 | --- | --- | --- |
-| [`AuthorizationPolicy`](/docs/reference/config/security/authorization-policy/) (including L7 features) | Beta | `targetRefs` |
+| [`AuthorizationPolicy`](/docs/reference/config/security/authorization-policy/) (including L7 features) | Stable | `targetRefs` |
 | [`RequestAuthentication`](/docs/reference/config/security/request_authentication/) | Beta | `targetRefs` |
 
 ### Considerations for authorization policies {#considerations}
@@ -128,3 +127,40 @@ spec:
       port: 9080
       weight: 10
 {{< /text >}}
+
+## Unsupported APIs with waypoints
+
+Some legacy Istio APIs are deliberately not supported by waypoints in ambient mode.  These APIs can still be used with [Istio Gateways](/docs/tasks/traffic-management/ingress/ingress-control/).
+
+### VirtualService
+
+Istio's legacy traffic routing API is not supported for configuring waypoint traffic routing, though it works in some circumstances.
+
+Any use of VirtualService with waypoints is considered Alpha, and may be subject to change in future releases.
+Istio's maintainers do not intend to remove this support, but will not be progressing it to [any further feature phase](/docs/releases/feature-stages).
+
+#### Migrating from VirtualService to Gateway API routes
+
+[Only a single VirtualService](/docs/reference/config/analysis/ist0109/) can be used for mesh traffic matching a certain hostname. However, multiple Gateway API routes can refer to the same host.
+
+This is especially relevant when you are migrating from VirtualService to Gateway API routes. If you create one or more HTTPRoutes which specify a Service that is also in use with a VirtualService, the HTTPRoute/s will apply and the VirtualService will not.
+
+To avoid this situation, users migrating from sidecars should look to convert their VirtualService configuration to Gateway API routes. The [ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway/) project has limited support for this use case. Caution is advised, especially for users who use [subset routing](/docs/concepts/traffic-management/#destination-rules)
+
+#### Using features that are not in Gateway API
+
+A small number of Istio's features cannot currently be expressed in Gateway API: for example, [fault injection](/docs/tasks/traffic-management/fault-injection/) and [direct response](/docs/reference/config/networking/virtual-service/#HTTPDirectResponse). It is technically possible to use VirtualService for these use cases, as long as the configured `hosts` do not conflict with the `parentRefs` of any Gateway API route as mentioned above.
+
+#### DestinationRule subsets
+
+Gateway API has no ability to address [subsets](/docs/reference/config/networking/destination-rule/#Subset). Instead, you must define additional Services which have a more granular selector than the original.
+
+The other features of DestinationRule are supported.
+
+#### Legacy Istio gateways
+
+Istio Gateways configured with VirtualService (i.e. where the `gateways` field refers to a named ingress gateway) can safely be mixed with waypoints which are configured with Gateway API routes.
+
+### EnvoyFilter
+
+EnvoyFilter is Istio's break-glass API for advanced configuration of Envoy proxies. Please note that **EnvoyFilter is not currently supported for any existing Istio version with waypoint proxies**. While it may be possible to use EnvoyFilter with waypoints in limited scenarios, its use is not supported, and is actively discouraged by the maintainers. The alpha API may break in future releases as it evolves. We expect official support will be provided at a later date.

content/en/docs/ambient/usage/waypoint/index.md

@@ -35,7 +35,7 @@ Waypoint proxies are deployed using Kubernetes Gateway resources.
 
 {{< boilerplate gateway-api-install-crds >}}
 
-You can use istioctl waypoint subcommands to generate, apply or list these resources.
+You can use `istioctl waypoint` subcommands to generate, apply or list these resources.
 
 After the waypoint is deployed, the entire namespace (or whichever services or pods you choose) must be [enrolled](#useawaypoint) to use it.
 
@@ -243,13 +243,11 @@ $ kubectl label serviceentries.networking.istio.io istio-site istio.io/use-waypo
 serviceentries.networking.istio.io/istio-site labeled
 {{< /text >}}
 
-### Cleaning up
+## Removing waypoints
 
 You can remove all waypoints from a namespace by doing the following:
 
 {{< text syntax=bash snip_id=delete_waypoint >}}
 $ istioctl waypoint delete --all -n default
 $ kubectl label ns default istio.io/use-waypoint-
 {{< /text >}}
-
-{{< boilerplate gateway-api-remove-crds >}}

content/en/docs/ambient/usage/waypoint/snips.sh

@@ -20,7 +20,6 @@
 #          docs/ambient/usage/waypoint/index.md
 ####################################################################################################
 source "content/en/boilerplates/snips/gateway-api-install-crds.sh"
-source "content/en/boilerplates/snips/gateway-api-remove-crds.sh"
 
 snip_check_ns_label() {
 kubectl get ns -L istio.io/dataplane-mode

content/en/docs/ambient/usage/waypoint/test.sh

@@ -17,6 +17,8 @@
 
 # @setup profile=ambient
 
+source "content/en/boilerplates/snips/gateway-api-remove-crds.sh"
+
 set -e
 set -u
 set -o pipefail

content/en/docs/ops/best-practices/traffic-management/index.md

@@ -279,7 +279,7 @@ caveats with this feature that must be considered carefully when using it.
    All such "catch-all" rules will be moved to the end of the list in the merged configuration, but
    since they catch all requests, whichever is applied first will essentially override and disable any others.
 1. A `VirtualService` can only be fragmented this way if it is bound to a gateway.
-   Host merging is not supported in sidecars.
+   Host merging is not supported in mesh routing (i.e. sidecars or waypoints).
 
 A `DestinationRule` can also be fragmented with similar merge semantics and restrictions.