docs: add notes for ports used in AuthPolicy/PeerAuth (#3075)

Signed-off-by: Peter Jausovec <peter.jausovec@solo.io>

Author: peterj

security/v1/authorization_policy.pb.go

@@ -168,7 +168,8 @@ import "type/v1beta1/selector.proto";
 //
 // The following is another example that sets `action` to `DENY` to create a deny policy.
 // It denies all the requests with `POST` method on port `8080` on all workloads
-// in the `foo` namespace.
+// in the `foo` namespace. Note the ports in the `ports` field refer to container ports,
+// not the Kubernetes Service ports.
 //
 // {{<tabset category-name="example">}}
 // {{<tab name="v1beta1" category-value="v1beta1">}}

security/v1/authorization_policy.proto

@@ -42,7 +42,7 @@ option go_package="istio.io/api/security/v1beta1";
 // ```
 // For mesh level, put the policy in root-namespace according to your Istio installation.
 //
-// Policies to allow both mTLS & plaintext traffic for all workloads under namespace `foo`, but
+// Policies to allow both mTLS and plaintext traffic for all workloads under namespace `foo`, but
 // require mTLS for workload `finance`.
 // ```yaml
 // apiVersion: security.istio.io/v1beta1
@@ -66,8 +66,9 @@ option go_package="istio.io/api/security/v1beta1";
 //   mtls:
 //     mode: STRICT
 // ```
-// Policy to allow mTLS strict for all workloads, but leave port 8080 to
-// plaintext:
+// Policy that enables strict mTLS for all workloads, but leaves the port `8080` to
+// plaintext. Note the port value in the `portLevelMtls` field refers to the port
+// of the workload, not the port of the Kubernetes service.
 // ```yaml
 // apiVersion: security.istio.io/v1beta1
 // kind: PeerAuthentication
@@ -84,8 +85,8 @@ option go_package="istio.io/api/security/v1beta1";
 //     8080:
 //       mode: DISABLE
 // ```
-// Policy to inherit mTLS mode from namespace (or mesh) settings, and overwrite
-// settings for port 8080
+// Policy that inherits mTLS mode from namespace (or mesh) settings, and disables
+// mTLS for workload port `8080`.
 // ```yaml
 // apiVersion: security.istio.io/v1beta1
 // kind: PeerAuthentication
@@ -137,7 +138,7 @@ message PeerAuthentication {
   // Mutual TLS settings.
   message MutualTLS {
     enum Mode {
-      // Inherit from parent, if has one. Otherwise treated as PERMISSIVE.
+      // Inherit from parent, if has one. Otherwise treated as `PERMISSIVE`.
       UNSET = 0;
 
       // Connection is not tunneled.
@@ -158,6 +159,7 @@ message PeerAuthentication {
   MutualTLS mtls = 2;
 
   // Port specific mutual TLS settings. These only apply when a workload selector
-  // is specified.
+  // is specified. The port refers to the port of the workload, not the port of the
+  // Kubernetes service.
   map<uint32, MutualTLS> port_level_mtls = 3;
 }