manual cherry-pick of istio#3184

Author: craigbox

security/v1/peer_authentication.pb.go

@@ -26,14 +26,19 @@ package istio.security.v1;
 
 option go_package="istio.io/api/security/v1";
 
-// {{< warning >}}
-// Development of PeerAuthentication is currently frozen and likely to be replaced in Ambient.
-// {{< /warning >}}
-// PeerAuthentication defines how traffic will be tunneled (or not) to the sidecar.
+// PeerAuthentication defines mutual TLS (mTLS) requirements for incoming connections.
+//
+// In sidecar mode, PeerAuthentication determines whether or not mTLS is allowed or required
+// for connections to an Envoy proxy sidecar.
+//
+// In ambient mode, security is transparently enabled for a pod by the ztunnel node agent.
+// (Traffic between proxies uses the HBONE protocol, which includes encryption with mTLS.)
+// Because of this, `DISABLE` mode is not supported.
+// `STRICT` mode is useful to ensure that connections that bypass the mesh are not possible.
 //
 // Examples:
 //
-// Policy to allow mTLS traffic for all workloads under namespace `foo`:
+// Policy to require mTLS traffic for all workloads under namespace `foo`:
 // ```yaml
 // apiVersion: security.istio.io/v1
 // kind: PeerAuthentication

security/v1/peer_authentication.proto

@@ -25,14 +25,18 @@ package istio.security.v1beta1;
 
 option go_package="istio.io/api/security/v1beta1";
 
-// {{< warning >}}
-// Development of PeerAuthentication is currently frozen and likely to be replaced in Ambient.
-// {{< /warning >}}
-// PeerAuthentication defines how traffic will be tunneled (or not) to the sidecar.
+// PeerAuthentication defines mutual TLS (mTLS) requirements for incoming connections.
 //
+// In sidecar mode, PeerAuthentication determines whether or not mTLS is allowed or required
+// for connections to an Envoy proxy sidecar.
+//
+// In ambient mode, security is transparently enabled for a pod by the ztunnel node agent.
+// (Traffic between proxies uses the HBONE protocol, which includes encryption with mTLS.)
+// Because of this, `DISABLE` mode is not supported.
+// `STRICT` mode is useful to ensure that connections that bypass the mesh are not possible.//
 // Examples:
 //
-// Policy to allow mTLS traffic for all workloads under namespace `foo`:
+// Policy to require mTLS traffic for all workloads under namespace `foo`:
 // ```yaml
 // apiVersion: security.istio.io/v1
 // kind: PeerAuthentication