:_mod-docs-content-type: ASSEMBLY
[id="network-policy-apis"]
= Understanding network policy APIs
include::_attributes/common-attributes.adoc[]
:context: network-policy-apis

toc::[]

Network policy is defined using both cluster-scoped and namespace-scoped network policy APIs. By defining network policy across these different levels, you can create sophisticated network security configurations for your clusters, including full multi-tenant isolation.

== Network policies and their scope

Cluster-scoped network policy:: Cluster and network administrators can use the AdminNetworkPolicy to define network policy at the cluster level. The AdminNetworkPolicy feature consists of two APIs: the `AdminNetworkPolicy` API and `BaselineAdminNetworkPolicy` API. These APIs are used to set rules that can be applied to the entire cluster, or delegated to the namespace-scoped `NetworkPolicy`.
+
Policies defined using the `AdminNetworkPolicy` API take precedence over all other policy types when set to "Allow" or "Deny". However, administrators can also use "Pass" to delegate responsibility for a given policy to the namespace-scoped `NetworkPolicy` to allow application developers and namespace tenants to control specific aspects of network security for their projects.
+
Policies defined using the `BaselineAdminNetworkPolicy` API apply only when no other network policy overrides them. When you use the `AdminNetworkPolicy` API to delegate an aspect of network policy to the namespace-scoped `NetworkPolicy`, you should also define a sensible minimum restriction in the `BaselineAdminNetworkPolicy`. This ensures a baseline level of network security at the cluster level in case the `NetworkPolicy` for a namespace does not provide sufficient protection.

Namespace-scoped network policy:: Application developers and namespace tenants can use the `NetworkPolicy` API to define network policy rules for a specific namespace. Rules in the `NetworkPolicy` for a namespace take precedence over cluster-wide rules configured using the BaselineAdminNetworkPolicy API, or for a cluster-wide rule that has been delegated or "passed" from the cluster-wide `AdminNetworkPolicy` API.

== How network policy is evaluated and applied

When a network connection is established, the network provider (default: OVN-Kubernetes) checks the connection details against network policy rules to determine how to handle the connection.

OVN-Kubernetes evaluates connections against network policy objects in the following order:

. Check for matches in the AdminNetworkPolicy tier.
.. If a connection matches an `Allow` or `Deny` rule, follow that rule and stop evaluating.
.. If a connection matches a `Pass` rule, move to the NetworkPolicy tier.
. Check for matches in the NetworkPolicy tier.
.. If a connection matches a rule, follow that rule and stop evaluating.
.. If no match is found, move to the BaselineAdminNetworkPolicy tier.
. Follow a matching rule in the BaselineAdminNetworkPolicy tier.

[id="img-ovn-kubernetes-network-policy-evaluation"]
.Evaluation of network policies by OVN-Kubernetes
image::615_OpenShift_OVN-K_ACLs_0324.png[OVN-Kubernetes Access Control List (ACL)]

// TODO OSDOCS-11830: If a change to network policies or other objects impacts an existing network connection...

// TODO OSDOCS-11830: Retaining old text until approved:
// OVN-Kubernetes CNI in {product-title} implements these network policies using Access Control List (ACL) Tiers to evaluate and apply them. ACLs are evaluated in descending order from Tier 1 to Tier 3.
// Tier 1 evaluates `AdminNetworkPolicy` (ANP) objects. Tier 2 evaluates `NetworkPolicy` objects. Tier 3 evaluates `BaselineAdminNetworkPolicy` (BANP) objects.
// ANPs are evaluated first. When the match is an ANP `allow` or `deny` rule, any existing `NetworkPolicy` and `BaselineAdminNetworkPolicy` (BANP) objects in the cluster are skipped from evaluation. When the match is an ANP `pass` rule, then evaluation moves from tier 1 of the ACL to tier 2 where the `NetworkPolicy` policy is evaluated. If no `NetworkPolicy` matches the traffic then evaluation moves from tier 2 ACLs to tier 3 ACLs where BANP is evaluated.

include::modules/nw-anp-np-reference.adoc[leveloffset=+1]