Skip to content

Add ambient mode caveats #3517

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add ambient mode caveats #3517

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
da3290f
Add ambient mode caveats
Stevenjin8 Jun 9, 2025
9026218
Subsets
Stevenjin8 Jun 9, 2025
9eefa13
Some corrections
Stevenjin8 Jun 23, 2025
31b8e88
Add warning about virtual service being alpha
Stevenjin8 Jul 22, 2025
2b22d03
Revert non-serviceentry related changes
Stevenjin8 Sep 15, 2025
47ed1aa
Typo and clarification
Stevenjin8 Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions networking/v1alpha3/service_entry.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions networking/v1alpha3/service_entry.pb.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions networking/v1alpha3/service_entry.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

//
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:MaxItems=256
// +protoc-gen-crd:list-value-validation:XValidation:message="hostname cannot be wildcard",rule="self != '*'"
Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the temporary limitation?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@craigbox same question about ingress

repeated string export_to = 7;

// If specified, the proxy will verify that the server certificate's
Expand Down
5 changes: 3 additions & 2 deletions networking/v1alpha3/sidecar.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions networking/v1alpha3/sidecar.pb.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions networking/v1alpha3/sidecar.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,9 @@ syntax = "proto3";
// $aliases: [/docs/reference/config/networking/v1alpha3/sidecar]

// `Sidecar` describes the configuration of the sidecar proxy that mediates
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

// 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// `Sidecar` only applies to Sidecar mode.

// By default, Istio will program all sidecar proxies in the mesh with the
// necessary configuration required to reach every workload instance in the mesh, as
// well as accept traffic on all the ports associated with the
// workload. The `Sidecar` configuration provides a way to fine tune the set of
Expand Down
17 changes: 17 additions & 0 deletions networking/v1alpha3/virtual_service.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions networking/v1alpha3/virtual_service.pb.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

17 changes: 17 additions & 0 deletions networking/v1alpha3/virtual_service.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,11 @@ syntax = "proto3";
// The source of traffic can also be matched in a routing rule. This allows routing
// to be customized for specific client contexts.
//
// *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.
//
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

// The following example on Kubernetes, routes all HTTP traffic by default to
// pods of the reviews service with label "version: v1". In addition,
// HTTP requests with path starting with /wpcatalog/ or /consumercatalog/ will
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. "support" is ambiguous

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

map<string, string> source_labels = 7;

// Names of gateways where the rule should be applied. Gateway names
Expand Down Expand Up @@ -859,6 +866,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.
string source_namespace = 13;

// The human readable prefix to use when emitting statistics for this route.
Expand Down Expand Up @@ -990,6 +999,8 @@ message L4MatchAttributes {
//
// **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.
map<string, string> source_labels = 4;

// Names of gateways where the rule should be applied. Gateway names
Expand All @@ -1003,6 +1014,8 @@ message L4MatchAttributes {
//
// **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.
string source_namespace = 6;
}

Expand Down Expand Up @@ -1034,6 +1047,8 @@ message TLSMatchAttributes {
//
// **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.
map<string, string> source_labels = 5;

// Names of gateways where the rule should be applied. Gateway names
Expand All @@ -1047,6 +1062,8 @@ message TLSMatchAttributes {
//
// **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.
string source_namespace = 7;
}

Expand Down