Merge pull request #77593 from JoeAldinger/OSDOCS-10930

OSDOCS-10930:ANP best practices

_topic_maps/_topic_map.yml

@@ -1298,6 +1298,8 @@ Topics:
       File: ovn-k-egress-nodes-networks-peer
     - Name: Troubleshooting
       File: ovn-k-anp-troubleshooting
+    - Name: Best practices
+      File: ovn-k-anp-recommended-practices
   - Name: Network policy
     Dir: network_policy
     Distros: openshift-enterprise, openshift-origin

modules/nw-ovn-k-anp-best-practices.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * list of assemblies where this module is included:
+// networking/network_security/AdminNetworkPolicy/nw-ovn-k-anp-recommended-practices.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="anp-best-practices_{context}"]
+= Designing AdminNetworkPolicy
+
+When building `AdminNetworkPolicy` (ANP) resources, you might consider the following when creating your policies:
+
+* Because there is no guarantee which policy will take precedence when overlapping ANP are created, you should create ANP at different priorities so that precedence is well defined.
+
+* Administrators must create ANP that apply to user namespaces not system namespaces.
+
+[IMPORTANT]
+====
+Applying ANP and `BaselineAdminNetworkPolicy` (BANP) to system namespaces (`default`, `kube-system`, any namespace whose name starts with `openshift-`, etc) is not supported, and this can leave your cluster unresponsive and in a non-functional state.
+====
+
+* Because `0-100` is the supported priority range, you might design your ANP to use a middle range like `30-70`. This leaves some placeholder
+for priorities before and after. Even in the middle range, you might want to leave gaps so that as your infrastructure requirements evolve over time, you are able to insert new ANPs when needed at the right priority level. If you pack your ANPs, then you might need to recreate all of them to accommodate any changes in the future.
+
+* When using `0.0.0.0/0` or `::/0` to create a strong `Deny` policy, ensure that you have higher priority `Allow` or `Pass` rules for essential traffic.
+
+* Use `Allow` as your `action` field when you want to ensure that a connection is allowed no matter what. An `Allow` rule in an ANP means that the connection will always be allowed, and `NetworkPolicy` will be ignored.
+
+* Use `Pass` as your `action` field to delegate the policy decision of allowing or denying the connection to the `NetworkPolicy` layer.
+
+* Ensure that the selectors across multiple rules do not overlap so that the same IPs do not appear in multiple policies, which can cause performance and scale limitations.
+
+* Avoid using `namedPorts` in conjunction with `PortNumber` and `PortRange` because this creates 6 ACLs and cause inefficiencies in your cluster.
+
+[id="considerations-using-banp_{context}"]
+== Considerations for using BaselineAdminNetworkPolicy
+
+* You can define only a single `BaselineAdminNetworkPolicy` (BANP) resource within a cluster. The following are supported uses for BANP that administrators might consider in designing their BANP:
+
+** You can set a default deny policy for cluster-local ingress in user namespaces. This BANP will force developers to have to add `NetworkPolicy` objects to allow the ingress traffic that they want to allow, and if they do not add network policies for ingress it will be denied.
+
+** You can set a default deny policy for cluster-local egress in user namespaces. This BANP will force developers to have to add `NetworkPolicy` objects to allow the egress traffic that they want to allow, and if they do not add network policies it will be denied.
+
+** You can set a default allow policy for egress to the in-cluster DNS service. Such a BANP ensures that the namespaced users do not have to set an allow egress `NetworkPolicy` to the in-cluster DNS service.
+
+** You can set an egress policy that allows internal egress traffic to all pods but denies access to all external endpoints (i.e `0.0.0.0/0` and `::/0`). This BANP allows user workloads to send traffic to other in-cluster endpoints, but not to external endpoints by default. `NetworkPolicy` can then be used by developers in order to allow their applications to send traffic to an explicit set of external services.
+
+* Ensure you scope your BANP so that it only denies traffic to user namespaces and not to system namespaces. This is because the system namespaces do not have `NetworkPolicy` objects to override your BANP.
+
+[id="differences-with-netpol_{context}"]
+== Differences to consider between AdminNetworkPolicy and NetworkPolicy
+
+* Unlike `NetworkPolicy` objects, you must use explicit labels to reference your workloads within ANP and BANP rather than using the empty (`{}`) catch all selector to avoid accidental traffic selection.
+
+[IMPORTANT]
+====
+An empty namespace selector applied to a infrastructure namespace can make your cluster unresponsive and in a non-functional state.
+====
+
+* In API semantics for ANP, you have to explicitly define allow or deny rules when you create the policy, unlike `NetworkPolicy` objects which have an implicit deny.
+
+* Unlike `NetworkPolicy` objects, `AdminNetworkPolicy` objects ingress rules are limited to in-cluster pods and namespaces so you cannot, and do not need to, set rules for ingress from the host network.

networking/network_security/AdminNetworkPolicy/ovn-k-anp-recommended-practices.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ovn-k-anp-recommended-practices"]
+= Best practices for AdminNetworkPolicy
+include::_attributes/common-attributes.adoc[]
+:context: ovn-k-anp-banp-metrics
+
+toc::[]
+
+This section provides best practices for the `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` resources.
+
+include::modules/nw-ovn-k-anp-best-practices.adoc[leveloffset=+1]