From da3290fee9e5af8059f3354c2663eed579577081 Mon Sep 17 00:00:00 2001
From: Steven Jin Xuan <sjinxuan@microsoft.com>
Date: Mon, 9 Jun 2025 13:37:38 -0400
Subject: [PATCH 1/3] Add ambient mode caveats

---
 networking/v1alpha3/service_entry.pb.go   | 2 ++
 networking/v1alpha3/service_entry.pb.html | 1 +
 networking/v1alpha3/service_entry.proto   | 3 +++
 networking/v1alpha3/sidecar.pb.go         | 5 +++--
 networking/v1alpha3/sidecar.pb.html       | 5 +++--
 networking/v1alpha3/sidecar.proto         | 5 +++--
 6 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/networking/v1alpha3/service_entry.pb.go b/networking/v1alpha3/service_entry.pb.go
index 8b1ce09126..cef23518ac 100644
--- a/networking/v1alpha3/service_entry.pb.go
+++ b/networking/v1alpha3/service_entry.pb.go
@@ -623,6 +623,8 @@ type ServiceEntry struct {
 	//     service accounts associated with the pods of the service, the
 	//     SANs specified here will also be verified.
 	//
+	// **NOTE 3:** Wildcard hostnames are not support in ambient mode.
+	//
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=256
 	// +protoc-gen-crd:list-value-validation:XValidation:message="hostname cannot be wildcard",rule="self != '*'"
diff --git a/networking/v1alpha3/service_entry.pb.html b/networking/v1alpha3/service_entry.pb.html
index fb5ada0db4..7739a67ad7 100644
--- a/networking/v1alpha3/service_entry.pb.html
+++ b/networking/v1alpha3/service_entry.pb.html
@@ -382,6 +382,7 @@ <h2 id="ServiceEntry">ServiceEntry</h2>
 service accounts associated with the pods of the service, the
 SANs specified here will also be verified.</li>
 </ol>
+<p><strong>NOTE 3:</strong> Wildcard hostnames are not support in ambient mode.</p>
 
 </td>
 </tr>
diff --git a/networking/v1alpha3/service_entry.proto b/networking/v1alpha3/service_entry.proto
index a551fee8c6..aa9557f197 100644
--- a/networking/v1alpha3/service_entry.proto
+++ b/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:** Wildcard hostnames are not support in ambient mode.
+  //
   // +kubebuilder:validation:MinItems=1
   // +kubebuilder:validation:MaxItems=256
   // +protoc-gen-crd:list-value-validation:XValidation:message="hostname cannot be wildcard",rule="self != '*'"
diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go
index bf86c1a082..9c2f2da418 100644
--- a/networking/v1alpha3/sidecar.pb.go
+++ b/networking/v1alpha3/sidecar.pb.go
@@ -25,8 +25,9 @@
 // $aliases: [/docs/reference/config/networking/v1alpha3/sidecar]
 
 // `Sidecar` describes the configuration of the sidecar proxy that mediates
-// 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.
+// 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
diff --git a/networking/v1alpha3/sidecar.pb.html b/networking/v1alpha3/sidecar.pb.html
index a4d72f07ba..6990863057 100644
--- a/networking/v1alpha3/sidecar.pb.html
+++ b/networking/v1alpha3/sidecar.pb.html
@@ -9,8 +9,9 @@
 number_of_entries: 8
 ---
 <p><code>Sidecar</code> describes the configuration of the sidecar proxy that mediates
-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.
+<code>Sidecar</code> 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 <code>Sidecar</code> configuration provides a way to fine tune the set of
diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto
index 2d60a306d5..332f6ceabb 100644
--- a/networking/v1alpha3/sidecar.proto
+++ b/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
-// 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.
+// 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

From 90262185e90d3f27e705cb925b006dafa4d0be52 Mon Sep 17 00:00:00 2001
From: Steven Jin Xuan <sjinxuan@microsoft.com>
Date: Mon, 9 Jun 2025 13:57:47 -0400
Subject: [PATCH 2/3] Subsets

---
 networking/v1alpha3/destination_rule.proto | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/networking/v1alpha3/destination_rule.proto b/networking/v1alpha3/destination_rule.proto
index 47c7b7a06c..6f14d605b5 100644
--- a/networking/v1alpha3/destination_rule.proto
+++ b/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.
+  // Define multiple services instead.
   repeated Subset subsets = 3;
 
   // A list of namespaces to which this destination rule is exported.
@@ -318,6 +320,8 @@ message TrafficPolicy {
 // **Note:** Policies specified for subsets will not take effect until
 // a route rule explicitly sends traffic to this subset.
 //
+// **Note:** Subsets are not supported in ambient mode. Define multiple services instead.
+//
 // One or more labels are typically required to identify the subset destination,
 // however, when the corresponding DestinationRule represents a host that
 // supports multiple SNI hosts (e.g., an egress gateway), a subset without labels

From 9eefa1371cedef2640298cd9e6d46f4826b94405 Mon Sep 17 00:00:00 2001
From: Steven Jin Xuan <sjinxuan@microsoft.com>
Date: Mon, 23 Jun 2025 13:49:57 -0400
Subject: [PATCH 3/3] Some corrections

* Remove subset notes
* Add source_* notes
---
 networking/v1alpha3/destination_rule.proto  |  4 ----
 networking/v1alpha3/service_entry.pb.go     |  5 ++++-
 networking/v1alpha3/service_entry.pb.html   |  4 +++-
 networking/v1alpha3/service_entry.proto     |  5 ++++-
 networking/v1alpha3/virtual_service.pb.go   | 12 ++++++++++++
 networking/v1alpha3/virtual_service.pb.html |  6 ++++++
 networking/v1alpha3/virtual_service.proto   | 12 ++++++++++++
 7 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/networking/v1alpha3/destination_rule.proto b/networking/v1alpha3/destination_rule.proto
index 6f14d605b5..47c7b7a06c 100644
--- a/networking/v1alpha3/destination_rule.proto
+++ b/networking/v1alpha3/destination_rule.proto
@@ -174,8 +174,6 @@ 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.
-  // Define multiple services instead.
   repeated Subset subsets = 3;
 
   // A list of namespaces to which this destination rule is exported.
@@ -320,8 +318,6 @@ message TrafficPolicy {
 // **Note:** Policies specified for subsets will not take effect until
 // a route rule explicitly sends traffic to this subset.
 //
-// **Note:** Subsets are not supported in ambient mode. Define multiple services instead.
-//
 // One or more labels are typically required to identify the subset destination,
 // however, when the corresponding DestinationRule represents a host that
 // supports multiple SNI hosts (e.g., an egress gateway), a subset without labels
diff --git a/networking/v1alpha3/service_entry.pb.go b/networking/v1alpha3/service_entry.pb.go
index cef23518ac..4a367f3f55 100644
--- a/networking/v1alpha3/service_entry.pb.go
+++ b/networking/v1alpha3/service_entry.pb.go
@@ -623,7 +623,7 @@ type ServiceEntry struct {
 	//     service accounts associated with the pods of the service, the
 	//     SANs specified here will also be verified.
 	//
-	// **NOTE 3:** Wildcard hostnames are not support in ambient mode.
+	// **NOTE 3:** Ambient mode does not support wildcard hostsnames.
 	//
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=256
@@ -689,6 +689,9 @@ type ServiceEntry struct {
 	// 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.
 	ExportTo []string `protobuf:"bytes,7,rep,name=export_to,json=exportTo,proto3" json:"export_to,omitempty"`
 	// If specified, the proxy will verify that the server certificate's
 	// subject alternate name matches one of the specified values.
diff --git a/networking/v1alpha3/service_entry.pb.html b/networking/v1alpha3/service_entry.pb.html
index 7739a67ad7..6c9fd3b772 100644
--- a/networking/v1alpha3/service_entry.pb.html
+++ b/networking/v1alpha3/service_entry.pb.html
@@ -382,7 +382,7 @@ <h2 id="ServiceEntry">ServiceEntry</h2>
 service accounts associated with the pods of the service, the
 SANs specified here will also be verified.</li>
 </ol>
-<p><strong>NOTE 3:</strong> Wildcard hostnames are not support in ambient mode.</p>
+<p><strong>NOTE 3:</strong> Ambient mode does not support wildcard hostsnames.</p>
 
 </td>
 </tr>
@@ -483,6 +483,8 @@ <h2 id="ServiceEntry">ServiceEntry</h2>
 <p>For a Kubernetes Service, the equivalent effect can be achieved by setting
 the annotation &ldquo;networking.istio.io/exportTo&rdquo; to a comma-separated list
 of namespace names.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field. Service entries will
+be exported to all namespaces.</p>
 
 </td>
 </tr>
diff --git a/networking/v1alpha3/service_entry.proto b/networking/v1alpha3/service_entry.proto
index aa9557f197..f22d16acc7 100644
--- a/networking/v1alpha3/service_entry.proto
+++ b/networking/v1alpha3/service_entry.proto
@@ -465,7 +465,7 @@ message ServiceEntry {
   //    service accounts associated with the pods of the service, the
   //    SANs specified here will also be verified.
   //
-  // **NOTE 3:** Wildcard hostnames are not support in ambient mode.
+  // **NOTE 3:** Ambient mode does not support wildcard hostsnames.
   //
   // +kubebuilder:validation:MinItems=1
   // +kubebuilder:validation:MaxItems=256
@@ -598,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.
   repeated string export_to = 7;
 
   // If specified, the proxy will verify that the server certificate's
diff --git a/networking/v1alpha3/virtual_service.pb.go b/networking/v1alpha3/virtual_service.pb.go
index b72b594e71..8cc266d00a 100644
--- a/networking/v1alpha3/virtual_service.pb.go
+++ b/networking/v1alpha3/virtual_service.pb.go
@@ -1395,6 +1395,8 @@ type HTTPMatchRequest struct {
 	//
 	// **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.
 	SourceLabels map[string]string `protobuf:"bytes,7,rep,name=source_labels,json=sourceLabels,proto3" json:"source_labels,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
 	// Names of gateways where the rule should be applied. Gateway names
 	// in the top-level `gateways` field of the VirtualService (if any) are overridden. The gateway
@@ -1431,6 +1433,8 @@ type HTTPMatchRequest struct {
 	//
 	// **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.
 	SourceNamespace string `protobuf:"bytes,13,opt,name=source_namespace,json=sourceNamespace,proto3" json:"source_namespace,omitempty"`
 	// The human readable prefix to use when emitting statistics for this route.
 	// The statistics are generated with prefix route.<stat_prefix>.
@@ -1795,6 +1799,8 @@ type L4MatchAttributes struct {
 	//
 	// **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.
 	SourceLabels map[string]string `protobuf:"bytes,4,rep,name=source_labels,json=sourceLabels,proto3" json:"source_labels,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
 	// Names of gateways where the rule should be applied. Gateway names
 	// in the top-level `gateways` field of the VirtualService (if any) are overridden. The gateway
@@ -1806,6 +1812,8 @@ type L4MatchAttributes struct {
 	//
 	// **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.
 	SourceNamespace string `protobuf:"bytes,6,opt,name=source_namespace,json=sourceNamespace,proto3" json:"source_namespace,omitempty"`
 	unknownFields   protoimpl.UnknownFields
 	sizeCache       protoimpl.SizeCache
@@ -1906,6 +1914,8 @@ type TLSMatchAttributes struct {
 	//
 	// **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.
 	SourceLabels map[string]string `protobuf:"bytes,5,rep,name=source_labels,json=sourceLabels,proto3" json:"source_labels,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
 	// Names of gateways where the rule should be applied. Gateway names
 	// in the top-level `gateways` field of the VirtualService (if any) are overridden. The gateway
@@ -1917,6 +1927,8 @@ type TLSMatchAttributes struct {
 	//
 	// **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.
 	SourceNamespace string `protobuf:"bytes,7,opt,name=source_namespace,json=sourceNamespace,proto3" json:"source_namespace,omitempty"`
 	unknownFields   protoimpl.UnknownFields
 	sizeCache       protoimpl.SizeCache
diff --git a/networking/v1alpha3/virtual_service.pb.html b/networking/v1alpha3/virtual_service.pb.html
index 637a497cc1..ea9a3a439d 100644
--- a/networking/v1alpha3/virtual_service.pb.html
+++ b/networking/v1alpha3/virtual_service.pb.html
@@ -1088,6 +1088,7 @@ <h2 id="HTTPMatchRequest">HTTPMatchRequest</h2>
 <code>mesh</code> for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
@@ -1162,6 +1163,7 @@ <h2 id="HTTPMatchRequest">HTTPMatchRequest</h2>
 it must include the reserved gateway <code>mesh</code> for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
@@ -1367,6 +1369,7 @@ <h2 id="L4MatchAttributes">L4MatchAttributes</h2>
 <code>mesh</code> in order for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
@@ -1391,6 +1394,7 @@ <h2 id="L4MatchAttributes">L4MatchAttributes</h2>
 it must include the reserved gateway <code>mesh</code> for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
@@ -1455,6 +1459,7 @@ <h2 id="TLSMatchAttributes">TLSMatchAttributes</h2>
 <code>mesh</code> in order for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
@@ -1479,6 +1484,7 @@ <h2 id="TLSMatchAttributes">TLSMatchAttributes</h2>
 it must include the reserved gateway <code>mesh</code> for this field to be applicable.</p>
 <p><strong>Note:</strong> This is not a runtime match, but is a selector; it filters which workloads the
 VirtualService applies to.</p>
+<p><strong>Note:</strong> Ambient mode does not support this field.</p>
 
 </td>
 </tr>
diff --git a/networking/v1alpha3/virtual_service.proto b/networking/v1alpha3/virtual_service.proto
index d81ad2d72c..466c32df75 100644
--- a/networking/v1alpha3/virtual_service.proto
+++ b/networking/v1alpha3/virtual_service.proto
@@ -818,6 +818,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.
   map<string, string> source_labels = 7;
 
   // Names of gateways where the rule should be applied. Gateway names
@@ -859,6 +861,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.
@@ -990,6 +994,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
@@ -1003,6 +1009,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;
 }
 
@@ -1034,6 +1042,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
@@ -1047,6 +1057,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;
 }