Add note on targetRef + authorization policy in multi-revision enviro…

…nment (#3023)

Signed-off-by: Keith Mattix II <[email protected]>
Co-authored-by: Keith Mattix II <[email protected]>

security/v1/authorization_policy.proto

@@ -467,19 +467,23 @@ message AuthorizationPolicy {
   // in the same namespace as the authorization policy. If the authorization policy is in the root namespace, the selector
   // will additionally match with workloads in all namespaces.
   //
-   // If the selector and the targetRef are not set, the selector will match all workloads. At most one of the selector 
+  // If the selector and the targetRef are not set, the selector will match all workloads. At most one of the selector
   // and targetRef can be set.
   istio.type.v1beta1.WorkloadSelector selector = 1;
 
-  // $hide_from_docs
-  // Optional. The targetRef specifies the gateway the policy should be 
-  // applied to. The targeted resource specified will determine which 
+  // Optional. The targetRef specifies the gateway the policy should be
+  // applied to. The targeted resource specified will determine which
   // workloads the authorization policy applies to. The targeted resource
   // must be a `Gateway` in the group `gateway.networking.k8s.io`. The
   // gateway must be in the same namespace as the authorization policy.
   //
   // If not set, the policy is applied as defined by the selector.
   // At most one of the selector and targetRef can be set.
+  //
+  // NOTE: If you are using the `targetRef` field in a multi-revision environment with Istio versions prior to 1.20,
+  // it is highly recommended that you pin the authorization policy to a revision running 1.20+ via the istio.io/rev label.
+  // This is to prevent proxies connected to older istiod control planes (that don't know about the targetRef field)
+  // from misinterpreting the policy as namespace-wide during the upgrade process.
   istio.type.v1beta1.PolicyTargetReference targetRef = 5;
 
   // Optional. A list of rules to match the request. A match occurs when at least one rule matches the request.

security/v1/request_authentication.proto

@@ -448,9 +448,8 @@ message RequestAuthentication {
   // If not set, the selector will match all workloads. At most one of the selector and targetRef can be set.
   istio.type.v1beta1.WorkloadSelector selector = 1;
 
-  // $hide_from_docs
-  // Optional. The targetRef specifies the gateway the policy should be 
-  // applied to. The targeted resource specified will determine which 
+  // Optional. The targetRef specifies the gateway the policy should be
+  // applied to. The targeted resource specified will determine which
   // workloads the request authentication policy to. The targeted resource
   // must be a `Gateway` in the group `gateway.networking.k8s.io`. The
   // gateway must be in the same namespace as the request authentication

security/v1beta1/authorization_policy.proto

@@ -467,19 +467,23 @@ message AuthorizationPolicy {
   // in the same namespace as the authorization policy. If the authorization policy is in the root namespace, the selector
   // will additionally match with workloads in all namespaces.
   //
-   // If the selector and the targetRef are not set, the selector will match all workloads. At most one of the selector 
+  // If the selector and the targetRef are not set, the selector will match all workloads. At most one of the selector
   // and targetRef can be set.
   istio.type.v1beta1.WorkloadSelector selector = 1;
 
-  // $hide_from_docs
-  // Optional. The targetRef specifies the gateway the policy should be 
-  // applied to. The targeted resource specified will determine which 
+  // Optional. The targetRef specifies the gateway the policy should be
+  // applied to. The targeted resource specified will determine which
   // workloads the authorization policy applies to. The targeted resource
   // must be a `Gateway` in the group `gateway.networking.k8s.io`. The
   // gateway must be in the same namespace as the authorization policy.
   //
   // If not set, the policy is applied as defined by the selector.
   // At most one of the selector and targetRef can be set.
+  //
+  // NOTE: If you are using the `targetRef` field in a multi-revision environment with Istio versions prior to 1.20,
+  // it is highly recommended that you pin the authorization policy to a revision running 1.20+ via the istio.io/rev label.
+  // This is to prevent proxies connected to older istiod control planes (that don't know about the targetRef field)
+  // from misinterpreting the policy as namespace-wide during the upgrade process.
   istio.type.v1beta1.PolicyTargetReference targetRef = 5;
 
   // Optional. A list of rules to match the request. A match occurs when at least one rule matches the request.

security/v1beta1/request_authentication.proto

@@ -447,9 +447,8 @@ message RequestAuthentication {
   // If not set, the selector will match all workloads. At most one of the selector and targetRef can be set.
   istio.type.v1beta1.WorkloadSelector selector = 1;
 
-  // $hide_from_docs
-  // Optional. The targetRef specifies the gateway the policy should be 
-  // applied to. The targeted resource specified will determine which 
+  // Optional. The targetRef specifies the gateway the policy should be
+  // applied to. The targeted resource specified will determine which
   // workloads the request authentication policy to. The targeted resource
   // must be a `Gateway` in the group `gateway.networking.k8s.io`. The
   // gateway must be in the same namespace as the request authentication