Add ambient mode caveats #3517

Stevenjin8 · 2025-06-09T17:49:14Z

Sidecar, ServiceEntry.exportTo and VirtualService.*.source_* are not used at all. While ServiceEntry wildcard hostnames also aren't supported.

istio-policy-bot · 2025-06-09T17:49:17Z

😊 Welcome @Stevenjin8! This is either your first contribution to the Istio api repo, or it's been
a while since you've been here.

You can learn more about the Istio working groups, Code of Conduct, and contribution guidelines
by referring to Contributing to Istio.

Thanks for contributing!

Courtesy of your friendly welcome wagon.

howardjohn · 2025-06-09T21:39:31Z

networking/v1alpha3/destination_rule.proto

@@ -174,6 +174,8 @@ message DestinationRule {

  // One or more named sets that represent individual versions of a
  // service. Traffic policies can be overridden at subset level.
+  // Note that subsets are not support in ambient mode.


This is not really true. Its not supported in HTTPRoute. Its supported in waypoints though

Ok I'm hearing contrasting things. It seems to me like most if not all of VirtualService works with waypoints. it's just alpha. So depending on who you ask, it might not be "supported." Where it gets tricky is when we start mixing Istio APIs and GWAPI. Like httproute and virtual service don't work together, and DR subsets aren't compatible with httproute.

Do most fields in VirtualService do what they say they do? Are there any fields that don't work?

Everything but sourceLabels and sourceVersion works.

Even ignoring VS, its not really that "subsets are not supported". At worst, there is no way to reference a subset in ambient. Which is maybe practically the same thing it just seems odd since you can absolutely create subsets in ambient

@howardjohn are you saying that the following config wouldn't do anything?

apiVersion: networking.istio.io/v1 kind: VirtualService metadata: name: reviews spec: hosts: - reviews http: - match: - headers: end-user: exact: jason route: - destination: host: reviews subset: v2 - route: - destination: host: reviews subset: v3

also, do you mean sourceNamespace instead of sourceVersion?

sourceNamespace yeah sorry.

And that VS is 100% fine in ambient. What I meant was "At worst [if you exclude VirtualServices due to them being alpha], there is no way to reference a subset". if you include VS, subset is perfectly fine.

* Remove subset notes * Add source_* notes

Stevenjin8 · 2025-07-22T18:17:53Z

no stale

hzxuzhonghu · 2025-07-24T01:27:43Z

networking/v1alpha3/service_entry.proto

@@ -595,6 +598,9 @@ message ServiceEntry {
  // For a Kubernetes Service, the equivalent effect can be achieved by setting
  // the annotation "networking.istio.io/exportTo" to a comma-separated list
  // of namespace names.
+  //
+  // **Note:** Ambient mode does not support this field. Service entries will
+  // be exported to all namespaces.


Is this the temporary limitation?

No, IIRC one of the big changes in ambient is that we want all workloads to have the same view of the mesh. So the same host corresponds to the same service/serviceentry regardless of the workload namespace

keithmattix

LGTM - these caveats are really important to call out. Thanks for doing this!

craigbox · 2025-07-28T23:00:04Z

networking/v1alpha3/virtual_service.proto

+// *Note for Ambient Users*: Support for `VirtualService` in Ambient mode is alpha, and
+// there are no plans to increase support.
+// Use [Gateway API](https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/#mesh-traffic)
+// for a stable traffic management API.
+//


Suggested change

// *Note for Ambient Users*: Support for `VirtualService` in Ambient mode is alpha, and

// there are no plans to increase support.

// Use [Gateway API](https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/#mesh-traffic)

// for a stable traffic management API.

//

// *Note for ambient mode users*: Waypoints are configured using Gateway API. [`VirtualService` is not supported for configuring waypoint traffic routing](https://istio.io/latest/docs/ambient/usage/l7-features/#virtualservice).

// 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](https://istio.io/latest/docs/releases/feature-stages/).

perhaps?

What about

// *Note for ambient mode users*: Waypoints should be configured Gateway API and // any use of [VirtualService with waypoints is alpha](https://istio.io/latest/docs/ambient/usage/l7-features/#virtualservice). // Istio’s maintainers do not intend to remove virtual service support, but will not be progressing it to [any further feature phase](https://istio.io/latest/docs/releases/feature-stages/).

I think "waypoints are configured using gateway api" is confusing since it suggests that they can only be configured using gwapi.

Similarly "Alpha, and may be subject to change in future releases" suggests that support could become beta, or even unsupport, however "but will not be progressing it to" suggests that it will be alpha forever (which is what we want to say)

craigbox · 2025-07-28T23:01:07Z

networking/v1alpha3/virtual_service.proto

@@ -818,6 +823,8 @@ message HTTPMatchRequest {
  //
  // **Note:** This is not a runtime match, but is a selector; it filters which workloads the
  // VirtualService applies to.
+  //
+  // **Note:** Ambient mode does not support this field.


We say above that ambient mode doesn't support anything.

How about:

Suggested change

// **Note:** Ambient mode does not support this field.

// **Note:** This feature has no effect in ambient mode.

?

Agreed. "support" is ambiguous

What about // **Note:** This field has no effect on Waypoint proxies... mm still doesn't feel too great.

craigbox · 2025-07-28T23:01:42Z

networking/v1alpha3/service_entry.proto

@@ -464,6 +464,9 @@ message ServiceEntry {
  // 1. subjectAltNames: In addition to verifying the SANs of the
  //    service accounts associated with the pods of the service, the
  //    SANs specified here will also be verified.
+  //
+  // **NOTE 3:** Ambient mode does not support wildcard hostsnames.


Suggested change

// **NOTE 3:** Ambient mode does not support wildcard hostsnames.

// **NOTE 3:** Wildcard hostnames are not supported in ambient mode.

@craigbox I imagine we get into "this works for ingress but not ztunnel/waypoint" too right?

craigbox · 2025-07-28T23:03:20Z

networking/v1alpha3/service_entry.proto

+  // **Note:** Ambient mode does not support this field. Service entries will
+  // be exported to all namespaces.


Suggested change

// **Note:** Ambient mode does not support this field. Service entries will

// be exported to all namespaces.

// **Note:** In ambient mode, service entries are exported to all namespaces,

// and this field has no effect.

@craigbox same question about ingress

craigbox · 2025-07-28T23:05:00Z

networking/v1alpha3/sidecar.proto

@@ -21,8 +21,9 @@ syntax = "proto3";
 // $aliases: [/docs/reference/config/networking/v1alpha3/sidecar]

 // `Sidecar` describes the configuration of the sidecar proxy that mediates


Suggested change

// `Sidecar` describes the configuration of the sidecar proxy that mediates

// In Istio's sidecar mode, the `Sidecar` resource describes the configuration of the proxy that mediates

and possibly a "Note 4" that says "Sidecar configuration is not required in ambient mode."?

Its required in sidecar mode either. Its more like, it has no effect in ambient mode

I so wish that this object had been named "SidecarScope" (and the same for legacy Gateway as GatewayConfig or something too)

craigbox · 2025-07-28T23:05:04Z

networking/v1alpha3/sidecar.proto

-// inbound and outbound communication to the workload instance it is attached to. By
-// default, Istio will program all sidecar proxies in the mesh with the
+// inbound and outbound communication to the workload instance it is attached to.
+// `Sidecar` only applies to Sidecar mode.


Suggested change

// `Sidecar` only applies to Sidecar mode.

craigbox · 2025-07-30T00:26:21Z

https://docs.google.com/document/d/1JjsPzOMJfu_evzgiRp-aJf1KDpa9ImyYrew__y5CTao/edit?tab=t.0#heading=h.8vlgwrna7yow for the broader terminology discussion

Stevenjin8 requested a review from a team as a code owner June 9, 2025 17:49

istio-testing added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Jun 9, 2025

Stevenjin8 added the release-notes-none Indicates a PR that does not require release notes. label Jun 9, 2025

istio-testing added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Jun 9, 2025

howardjohn requested changes Jun 9, 2025

View reviewed changes

Stevenjin8 force-pushed the service-export branch from 258c9b3 to ca9ed35 Compare June 23, 2025 17:50

istio-testing added the needs-rebase Indicates a PR needs to be rebased before being merged label Jun 23, 2025

Stevenjin8 added 2 commits June 23, 2025 13:51

Add ambient mode caveats

da3290f

Subsets

9026218

Stevenjin8 force-pushed the service-export branch from ca9ed35 to e3c5b91 Compare June 23, 2025 17:52

istio-testing removed the needs-rebase Indicates a PR needs to be rebased before being merged label Jun 23, 2025

Some corrections

9eefa13

* Remove subset notes * Add source_* notes

Stevenjin8 force-pushed the service-export branch from e3c5b91 to 9eefa13 Compare June 23, 2025 17:56

Stevenjin8 requested a review from howardjohn June 23, 2025 17:59

Add warning about virtual service being alpha

31b8e88

istio-policy-bot added the lifecycle/stale Indicates a PR or issue hasn't been manipulated by an Istio team member for a while label Jul 22, 2025

istio-policy-bot removed the lifecycle/stale Indicates a PR or issue hasn't been manipulated by an Istio team member for a while label Jul 22, 2025

hzxuzhonghu reviewed Jul 24, 2025

View reviewed changes

keithmattix reviewed Jul 28, 2025

View reviewed changes

craigbox reviewed Jul 28, 2025

View reviewed changes

	// Note: Ambient mode does not support this field.
	// Note: This feature has no effect in ambient mode.

	// NOTE 3: Ambient mode does not support wildcard hostsnames.
	// NOTE 3: Wildcard hostnames are not supported in ambient mode.

		// Note: Ambient mode does not support this field. Service entries will
		// be exported to all namespaces.

		@@ -21,8 +21,9 @@ syntax = "proto3";
		// $aliases: [/docs/reference/config/networking/v1alpha3/sidecar]

		// `Sidecar` describes the configuration of the sidecar proxy that mediates

	// `Sidecar` describes the configuration of the sidecar proxy that mediates
	// In Istio's sidecar mode, the `Sidecar` resource describes the configuration of the proxy that mediates

Add ambient mode caveats #3517

Are you sure you want to change the base?

Add ambient mode caveats #3517

Uh oh!

Conversation

Stevenjin8 commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

istio-policy-bot commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Stevenjin8 commented Jul 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keithmattix left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

craigbox commented Jul 30, 2025

Uh oh!

Uh oh!

Stevenjin8 commented Jun 9, 2025 •

edited

Loading