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

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

security/v1/authorization_policy.pb.go

@@ -170,7 +170,8 @@
 //
 // 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

@@ -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/v1beta1/peer_authentication.pb.go

@@ -44,7 +44,7 @@ const (
 type PeerAuthentication_MutualTLS_Mode int32
 
 const (
-	// Inherit from parent, if has one. Otherwise treated as PERMISSIVE.
+	// Inherit from parent, if has one. Otherwise treated as `PERMISSIVE`.
 	PeerAuthentication_MutualTLS_UNSET PeerAuthentication_MutualTLS_Mode = 0
 	// Connection is not tunneled.
 	PeerAuthentication_MutualTLS_DISABLE PeerAuthentication_MutualTLS_Mode = 1
@@ -118,7 +118,7 @@ func (PeerAuthentication_MutualTLS_Mode) EnumDescriptor() ([]byte, []int) {
 // ```
 // 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
@@ -150,8 +150,9 @@ func (PeerAuthentication_MutualTLS_Mode) EnumDescriptor() ([]byte, []int) {
 //	  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
@@ -172,8 +173,8 @@ func (PeerAuthentication_MutualTLS_Mode) EnumDescriptor() ([]byte, []int) {
 //	    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
@@ -232,7 +233,8 @@ type PeerAuthentication struct {
 	// Mutual TLS settings for workload. If not defined, inherit from parent.
 	Mtls *PeerAuthentication_MutualTLS `protobuf:"bytes,2,opt,name=mtls,proto3" json:"mtls,omitempty"`
 	// 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.
 	PortLevelMtls map[uint32]*PeerAuthentication_MutualTLS `protobuf:"bytes,3,rep,name=port_level_mtls,json=portLevelMtls,proto3" json:"port_level_mtls,omitempty" protobuf_key:"varint,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
 }
 

security/v1beta1/peer_authentication.pb.html

@@ -23,7 +23,7 @@ spec:
     mode: STRICT
 </code></pre>
 <p>For mesh level, put the policy in root-namespace according to your Istio installation.</p>
-<p>Policies to allow both mTLS &amp; plaintext traffic for all workloads under namespace <code>foo</code>, but
+<p>Policies to allow both mTLS and plaintext traffic for all workloads under namespace <code>foo</code>, but
 require mTLS for workload <code>finance</code>.</p>
 <pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
 kind: PeerAuthentication
@@ -46,8 +46,9 @@ spec:
   mtls:
     mode: STRICT
 </code></pre>
-<p>Policy to allow mTLS strict for all workloads, but leave port 8080 to
-plaintext:</p>
+<p>Policy that enables strict mTLS for all workloads, but leaves the port <code>8080</code> to
+plaintext. Note the port value in the <code>portLevelMtls</code> field refers to the port
+of the workload, not the port of the Kubernetes service.</p>
 <pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
 kind: PeerAuthentication
 metadata:
@@ -63,8 +64,8 @@ spec:
     8080:
       mode: DISABLE
 </code></pre>
-<p>Policy to inherit mTLS mode from namespace (or mesh) settings, and overwrite
-settings for port 8080</p>
+<p>Policy that inherits mTLS mode from namespace (or mesh) settings, and disables
+mTLS for workload port <code>8080</code>.</p>
 <pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
 kind: PeerAuthentication
 metadata:
@@ -121,7 +122,8 @@ No
 <td><code>map&lt;uint32,&nbsp;<a href="#PeerAuthentication-MutualTLS">MutualTLS</a>&gt;</code></td>
 <td>
 <p>Port specific mutual TLS settings. These only apply when a workload selector
-is specified.</p>
+is specified. The port refers to the port of the workload, not the port of the
+Kubernetes service.</p>
 
 </td>
 <td>
@@ -172,7 +174,7 @@ No
 <tr id="PeerAuthentication-MutualTLS-Mode-UNSET">
 <td><code>UNSET</code></td>
 <td>
-<p>Inherit from parent, if has one. Otherwise treated as PERMISSIVE.</p>
+<p>Inherit from parent, if has one. Otherwise treated as <code>PERMISSIVE</code>.</p>
 
 </td>
 </tr>

security/v1beta1/peer_authentication.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;
 }