From 5fba6f1a8f0b38b0b647e8682ffc51bb0955aba5 Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 15 Jul 2025 13:20:41 +1200 Subject: [PATCH 1/7] clarify support for VirtualService in waypoints --- .../gateway-api-gamma-experimental.md | 2 +- .../docs/ambient/usage/add-workloads/index.md | 12 +++-- .../docs/ambient/usage/l7-features/index.md | 54 +++++++++++++++---- .../en/docs/ambient/usage/waypoint/index.md | 6 +-- .../traffic-management/index.md | 2 +- 5 files changed, 56 insertions(+), 20 deletions(-) diff --git a/content/en/boilerplates/gateway-api-gamma-experimental.md b/content/en/boilerplates/gateway-api-gamma-experimental.md index 04ff23250fca..a4804d3acb5a 100644 --- a/content/en/boilerplates/gateway-api-gamma-experimental.md +++ b/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: diff --git a/content/en/docs/ambient/usage/add-workloads/index.md b/content/en/docs/ambient/usage/add-workloads/index.md index 91c8ccd6b2c3..02d2360cc7f7 100644 --- a/content/en/docs/ambient/usage/add-workloads/index.md +++ b/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. diff --git a/content/en/docs/ambient/usage/l7-features/index.md b/content/en/docs/ambient/usage/l7-features/index.md index bb45d0c06706..e32adc78b712 100644 --- a/content/en/docs/ambient/usage/l7-features/index.md +++ b/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](#unsupported-apis). {{< /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](https://istio.io/latest/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. diff --git a/content/en/docs/ambient/usage/waypoint/index.md b/content/en/docs/ambient/usage/waypoint/index.md index f8a8b1dfa17a..3d969c8186c2 100644 --- a/content/en/docs/ambient/usage/waypoint/index.md +++ b/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,7 +243,7 @@ $ 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: @@ -251,5 +251,3 @@ You can remove all waypoints from a namespace by doing the following: $ istioctl waypoint delete --all -n default $ kubectl label ns default istio.io/use-waypoint- {{< /text >}} - -{{< boilerplate gateway-api-remove-crds >}} diff --git a/content/en/docs/ops/best-practices/traffic-management/index.md b/content/en/docs/ops/best-practices/traffic-management/index.md index 5f0fdf9a9990..0fa299decdd0 100644 --- a/content/en/docs/ops/best-practices/traffic-management/index.md +++ b/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. From 1d50bdd43e85a0edb8758fbfaa77e8b6e004cb11 Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 15 Jul 2025 13:27:37 +1200 Subject: [PATCH 2/7] teeny little lintify --- .spelling | 2 ++ content/en/docs/ambient/usage/l7-features/index.md | 8 ++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.spelling b/.spelling index 35233630823d..944c4afaa842 100644 --- a/.spelling +++ b/.spelling @@ -611,6 +611,7 @@ httpbin httpbin.foo.svc.cluster.local httpbin.org HTTPRoute +HTTPRoutes HTTPS https Hu @@ -630,6 +631,7 @@ impactful incentivized Incrementality Indo-Pacific +ingress2gateway initContainer initializer initializers diff --git a/content/en/docs/ambient/usage/l7-features/index.md b/content/en/docs/ambient/usage/l7-features/index.md index e32adc78b712..13de7a7f1c68 100644 --- a/content/en/docs/ambient/usage/l7-features/index.md +++ b/content/en/docs/ambient/usage/l7-features/index.md @@ -132,16 +132,16 @@ spec: 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 +### VirtualService -Istio's legacy traffic routing API is not supported for configuring waypoint traffic routing, though it works in some circumstances. +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](https://istio.io/latest/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. +[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. @@ -149,7 +149,7 @@ To avoid this situation, users migrating from sidecars should look to convert th #### 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. +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 From e7b8bad4626943c4606eb070870be842afe615a4 Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 15 Jul 2025 13:45:08 +1200 Subject: [PATCH 3/7] teeny little genify --- content/en/docs/ambient/usage/waypoint/snips.sh | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/ambient/usage/waypoint/snips.sh b/content/en/docs/ambient/usage/waypoint/snips.sh index 69e216b3f9d6..8ac0e664dd0a 100644 --- a/content/en/docs/ambient/usage/waypoint/snips.sh +++ b/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 From 761041ef103f5940046a1da3d54df17e94c31de7 Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 15 Jul 2025 14:12:01 +1200 Subject: [PATCH 4/7] fix test --- content/en/docs/ambient/usage/waypoint/test.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/ambient/usage/waypoint/test.sh b/content/en/docs/ambient/usage/waypoint/test.sh index fd2f57e2cd4d..baec690676d4 100644 --- a/content/en/docs/ambient/usage/waypoint/test.sh +++ b/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 From 32b72d72eae0f88d5709b35bb419f93b2e797aef Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 29 Jul 2025 11:22:16 +1200 Subject: [PATCH 5/7] work around #16708 --- content/en/docs/ambient/usage/l7-features/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ambient/usage/l7-features/index.md b/content/en/docs/ambient/usage/l7-features/index.md index 13de7a7f1c68..a5001916ee13 100644 --- a/content/en/docs/ambient/usage/l7-features/index.md +++ b/content/en/docs/ambient/usage/l7-features/index.md @@ -9,7 +9,7 @@ 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 {{< gloss "gateway api" >}}Gateway API{{< /gloss >}}. {{< warning >}} -The VirtualService and EnvoyFilter APIs are not supported in waypoints. [Read more below](#unsupported-apis). +The VirtualService and EnvoyFilter APIs are not supported in waypoints. [Read more below](/docs/ambient/usage/l7-features/#unsupported-apis). {{< /warning >}} ## Route and policy attachment From 433455641cf9a1a9599246b8c809d17e50b527ea Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 29 Jul 2025 14:44:08 +1200 Subject: [PATCH 6/7] correct link --- content/en/docs/ambient/usage/l7-features/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ambient/usage/l7-features/index.md b/content/en/docs/ambient/usage/l7-features/index.md index a5001916ee13..bc8bdbddd393 100644 --- a/content/en/docs/ambient/usage/l7-features/index.md +++ b/content/en/docs/ambient/usage/l7-features/index.md @@ -9,7 +9,7 @@ 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 {{< gloss "gateway api" >}}Gateway API{{< /gloss >}}. {{< warning >}} -The VirtualService and EnvoyFilter APIs are not supported in waypoints. [Read more below](/docs/ambient/usage/l7-features/#unsupported-apis). +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 From 3bc938d4c8cff8e2e7fdccc5a5fb766a4786d2f8 Mon Sep 17 00:00:00 2001 From: Craig Box Date: Thu, 31 Jul 2025 12:04:07 +1200 Subject: [PATCH 7/7] update language --- content/en/docs/ambient/usage/l7-features/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/ambient/usage/l7-features/index.md b/content/en/docs/ambient/usage/l7-features/index.md index bc8bdbddd393..d24262c2b88f 100644 --- a/content/en/docs/ambient/usage/l7-features/index.md +++ b/content/en/docs/ambient/usage/l7-features/index.md @@ -130,11 +130,11 @@ spec: ## 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/). +Some Istio APIs are deliberately not supported by waypoints in ambient mode. These APIs can still be used with [classic Istio Gateways](/docs/tasks/traffic-management/ingress/ingress-control/) in an ambient mesh. ### VirtualService -Istio's legacy traffic routing API is not supported for configuring waypoint traffic routing, though it works in some circumstances. +Istio's classic 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). @@ -157,9 +157,9 @@ Gateway API has no ability to address [subsets](/docs/reference/config/networkin The other features of DestinationRule are supported. -#### Legacy Istio gateways +#### Classic 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. +[Classic Istio Gateways](/docs/reference/config/networking/gateway/) can be used to route traffic into an ambient mesh. These can still be configured with VirtualService (i.e. where the `gateways` field refers to a named ingress gateway), alongside waypoints which are configured with Gateway API routes. ### EnvoyFilter