Add documentation regarding Namespaces field (#2271)

Add doc and sample yaml in antrea-network-policy.md to describe
Namespaces field in ACNP.

Signed-off-by: abhiraut <rauta@vmware.com>

docs/antrea-network-policy.md

@@ -10,6 +10,9 @@
   - [kubectl commands for Tier](#kubectl-commands-for-tier)
 - [Antrea ClusterNetworkPolicy](#antrea-clusternetworkpolicy)
   - [The Antrea ClusterNetworkPolicy resource](#the-antrea-clusternetworkpolicy-resource)
+    - [ACNP with stand alone selectors](#acnp-with-stand-alone-selectors)
+    - [ACNP with ClusterGroup reference](#acnp-with-clustergroup-reference)
+    - [ACNP for default Namespace isolation](#acnp-for-default-namespace-isolation)
   - [Behavior of <em>to</em> and <em>from</em> selectors](#behavior-of-to-and-from-selectors)
   - [Key differences from K8s NetworkPolicy](#key-differences-from-k8s-networkpolicy)
   - [kubectl commands for Antrea ClusterNetworkPolicy](#kubectl-commands-for-antrea-clusternetworkpolicy)
@@ -176,7 +179,9 @@ rule belonging to a K8s NetworkPolicy.
 
 ### The Antrea ClusterNetworkPolicy resource
 
-Example ClusterNetworkPolicies might look like this:
+Example ClusterNetworkPolicies might look like these:
+
+#### ACNP with stand alone selectors
 
 ```yaml
 apiVersion: crd.antrea.io/v1alpha1
@@ -223,7 +228,11 @@ spec:
             port: 5978
         name: DropToThirdParty
         enableLogging: true
----
+```
+
+#### ACNP with ClusterGroup reference
+
+```yaml
 apiVersion: crd.antrea.io/v1alpha1
 kind: ClusterNetworkPolicy
 metadata:
@@ -256,6 +265,44 @@ spec:
       enableLogging: true
 ```
 
+#### ACNP for default Namespace isolation
+
+```yaml
+apiVersion: crd.antrea.io/v1alpha1
+kind: ClusterNetworkPolicy
+metadata:
+  name: default-ns-isolation
+spec:
+  priority: 2
+  tier: baseline
+  appliedTo:
+    - namespaceSelector: {}       # Selects all Namespaces in the cluster
+  ingress:
+    - action: Allow
+      from:
+        - namespaces:
+            match: self           # Allow from Pods from same Namespace
+      name: AllowFromSameNS
+      enableLogging: false
+    - action: Drop
+      from:
+        - namespaceSelector: {}   # Drop from Pods from other all Namespaces
+      name: DropFromAllOtherNS
+      enableLogging: true
+  egress:
+    - action: Allow
+      to:
+        - namespaces:
+            match: self           # Allow to Pods from same Namespace
+      name: AllowToSameNS
+      enableLogging: false
+    - action: Drop
+      to:
+        - namespaceSelector: {}   # Drop to Pods from all other Namespaces
+      name: DropToAllOtherNS
+      enableLogging: true
+```
+
 **spec**: The ClusterNetworkPolicy `spec` has all the information needed to
 define a cluster-wide security policy.
 
@@ -272,10 +319,10 @@ An IPBlock ClusterGroup referenced in an `appliedTo` field will be ignored,
 and the policy will have no effect.
 This `appliedTo` field must not be set, if `appliedTo` per
 rule is used.
-In the first example, the policy applies to Pods, which either match the labels
+In the [first example](#acnp-with-stand-alone-selectors), the policy applies to Pods, which either match the labels
 "role=db" in all the Namespaces, or are from Namespaces which match the
 labels "env=prod".
-The second example policy applies to all network endpoints selected by the
+The [second example](#acnp-with-clustergroup-reference) policy applies to all network endpoints selected by the
 "test-cg-with-db-selector" ClusterGroup.
 
 **priority**: The `priority` field determines the relative priority of the
@@ -306,11 +353,11 @@ name of some other rules in the same policy, it will cause a conflict,
 and the policy will be rejected.
 A ClusterGroup name can be set in the `group` field of an ingress `from` section in place
 of stand-alone selectors to allow traffic from workloads/ipBlocks set in the ClusterGroup.
-The first example policy contains a single rule, which allows matched traffic on a
+The [first example](#acnp-with-stand-alone-selectors) policy contains a single rule, which allows matched traffic on a
 single port, from one of two sources: the first specified by a `podSelector`
 and the second specified by a combination of a `podSelector` and a
 `namespaceSelector`.
-The second example policy contains a single rule, which allows matched traffic on
+The [second example](#acnp-with-clustergroup-reference) policy contains a single rule, which allows matched traffic on
 multiple TCP ports (8000 through 9000 included, plus 6379) from all network endpoints
 selected by the "test-cg-with-frontend-selector" ClusterGroup.
 **Note**: The order in which the ingress rules are set matter, i.e. rules will
@@ -327,9 +374,9 @@ a rule, it will be auto-generated by Antrea. The rule name auto-generation proce
 is the same as ingress rules.
 A ClusterGroup name can be set in the `group` field of a egress `to` section in place
 of stand-alone selectors to allow traffic to workloads/ipBlocks set in the ClusterGroup.
-The first example policy contains a single rule, which drops matched traffic on a
+The [first example](#acnp-with-stand-alone-selectors) policy contains a single rule, which drops matched traffic on a
 single port, to the 10.0.10.0/24 subnet specified by the `ipBlock` field.
-The second example policy contains a single rule, which drops matched traffic on
+The [second example](#acnp-with-clustergroup-reference) policy contains a single rule, which drops matched traffic on
 TCP port 5978 to all network endpoints selected by the "test-cg-with-ip-block"
 ClusterGroup.
 **Note**: The order in which the egress rules are set matter, i.e. rules will
@@ -365,19 +412,33 @@ Usage of ClusterGroups along with stand-alone selectors is not allowed.
 
 ### Behavior of *to* and *from* selectors
 
-There are four kinds of selectors that can be specified in an ingress `from`
+There are six kinds of selectors that can be specified in an ingress `from`
 section or egress `to` section:
 
 **podSelector**: This selects particular Pods from all Namespaces as "sources",
 if set in `ingress` section, or as "destinations", if set in `egress` section.
 
 **namespaceSelector**: This selects particular Namespaces for which all Pods
-are grouped as `ingress` "sources" or `egress` "destinations".
+are grouped as `ingress` "sources" or `egress` "destinations". Cannot be set
+with `namespaces` field.
 
 **podSelector** and **namespaceSelector**:  A single to/from entry that
 specifies both namespaceSelector and podSelector selects particular Pods within
 particular Namespaces.
 
+**namespaces**: A `namespaces` field allows users to perform advanced matching on
+Namespace objects which cannot be done via label selectors. Currently, the
+`namespaces` field has only one matching strategy, `self`. If set to `self`, it indicates
+that the corresponding `podSelector` (or all Pods if `podSelector` is not set)
+should only select Pods belonging to the same Namespace as the workload targeted
+(either through a policy-level AppliedTo or a rule-level Applied-To) by the current
+ingress or egress rule. This enables policy writers to create per-Namespace rules within a
+single policy. See the [third example](#acnp-for-default-namespace-isolation) YAML above. This field is
+optional and cannot be set along with a `namespaceSelector` within the same peer.
+
+**group**: A `group` refers to a ClusterGroup to which this ingress/egress peer, or
+an `appliedTo` must resolve to. More information on ClusterGroups can be found [here](#clustergroup).
+
 **ipBlock**: This selects particular IP CIDR ranges to allow as `ingress`
 "sources" or `egress` "destinations". These should be cluster-external IPs,
 since Pod IPs are ephemeral and unpredictable.
@@ -491,6 +552,8 @@ policy CRDs.
   NetworkPolicy is created. This behavior is similar to the K8s NetworkPolicy.
 - Antrea NetworkPolicy only supports stand-alone selectors. i.e. no support for
   ClusterGroup references.
+- Antrea NetworkPolicy does not support `namespaces` field within a peer, as ANP
+  themselves are scoped to a single Namespace.
 
 ### kubectl commands for Antrea NetworkPolicy