Skip to content

Commit b068f95

Browse files
JoeAldingerJoeAldinger
authored
Merge pull request #70800 from JoeAldinger/OSDOCS-6248
OSDOCS-6248:adds AdminNetworkPolicy to OVN-K
2 parents af83e5f + d1b268f commit b068f95

File tree

5 files changed

+371
-0
lines changed

5 files changed

+371
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1427,6 +1427,8 @@ Topics:
14271427
File: ovn-kubernetes-architecture-assembly
14281428
- Name: OVN-Kubernetes troubleshooting
14291429
File: ovn-kubernetes-troubleshooting-sources
1430+
- Name: OVN-Kubernetes network policy
1431+
File: ovn-k-network-policy
14301432
- Name: OVN-Kubernetes traffic tracing
14311433
File: ovn-kubernetes-tracing-using-ovntrace
14321434
- Name: Migrating from the OpenShift SDN network plugin

‎modules/nw-ovn-k-adminnetwork-policy-action-rules.adoc

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ovn-k-network-policy.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="adminnetworkpolicy-actions-for-rules_{context}"]
7+
= AdminNetworkPolicy actions for rules
8+
As an administrator, you can set `Allow`, `Deny`, or `Pass` as the `action` field for your `AdminNetworkPolicy` rules. Because OVN-Kubernetes uses a tiered ACLs to evaluate network traffic rules, ANP allow you to set very strong policy rules that can only be changed by an administrator modifying them, deleting the rule, or overriding them by setting a higher priority rule.
9+
10+
[discrete]
11+
[id="adminnetworkpolicy-allow-example_{context}"]
12+
== AdminNetworkPolicy Allow example
13+
The following ANP that is defined at priority 9 ensures all ingress traffic is allowed from the `monitoring` namespace towards any tenant (all other namespaces) in the cluster.
14+
15+
16+
.Example YAML file for a strong `Allow` ANP
17+
[%collapsible]
18+
====
19+
[source,yaml]
20+
----
21+
apiVersion: policy.networking.k8s.io/v1alpha1
22+
kind: AdminNetworkPolicy
23+
metadata:
24+
name: allow-monitoring
25+
spec:
26+
priority: 9
27+
subject:
28+
namespaces: {}
29+
ingress:
30+
- name: "allow-ingress-from-monitoring"
31+
action: "Allow"
32+
from:
33+
- namespaces:
34+
namespaceSelector:
35+
matchLabels:
36+
kubernetes.io/metadata.name: monitoring
37+
# ...
38+
----
39+
====
40+
This is an example of a strong `Allow` ANP because it is non-overridable by all the parties involved. No tenants can block themselves from being monitored using `NetworkPolicy` objects and the monitoring tenant also has no say in what it can or cannot monitor.
41+
42+
[discrete]
43+
[id="adminnetworkpolicy-deny-example_{context}"]
44+
== AdminNetworkPolicy Deny example
45+
The following ANP that is defined at priority 5 ensures all ingress traffic from the `monitoring` namespace is blocked towards restricted tenants (namespaces that have labels `security: restricted`).
46+
47+
.Example YAML file for a strong `Deny` ANP
48+
[%collapsible]
49+
====
50+
[source,yaml]
51+
----
52+
apiVersion: policy.networking.k8s.io/v1alpha1
53+
kind: AdminNetworkPolicy
54+
metadata:
55+
name: block-monitoring
56+
spec:
57+
priority: 5
58+
subject:
59+
namespaces:
60+
matchLabels:
61+
security: restricted
62+
ingress:
63+
- name: "deny-ingress-from-monitoring"
64+
action: "Deny"
65+
from:
66+
- namespaces:
67+
namespaceSelector:
68+
matchLabels:
69+
kubernetes.io/metadata.name: monitoring
70+
# ...
71+
----
72+
====
73+
This is a strong `Deny` ANP that is non-overridable by all the parties involved. The restricted tenant owners cannot authorize themselves to allow monitoring traffic, and the infrastructure’s monitoring service cannot scrape anything from these sensitive namespaces.
74+
75+
When combined with the strong `Allow` example, the `block-monitoring` ANP has a lower priority value giving it higher precedence, which ensures restricted tenants are never monitored.
76+
77+
[discrete]
78+
[id="adminnetworkpolicy-pass-example_{context}"]
79+
== AdminNetworkPolicy Pass example
80+
TThe following ANP that is defined at priority 7 ensures all ingress traffic from the `monitoring` namespace towards internal infrastructure tenants (namespaces that have labels `security: internal`) are passed on to tier 2 of the ACLs and evaluated by the namespaces’ `NetworkPolicy` objects.
81+
82+
.Example YAML file for a strong `Pass` ANP
83+
[%collapsible]
84+
====
85+
[source,yaml]
86+
----
87+
apiVersion: policy.networking.k8s.io/v1alpha1
88+
kind: AdminNetworkPolicy
89+
metadata:
90+
name: pass-monitoring
91+
spec:
92+
priority: 7
93+
subject:
94+
namespaces:
95+
matchLabels:
96+
security: internal
97+
ingress:
98+
- name: "pass-ingress-from-monitoring"
99+
action: "Pass"
100+
from:
101+
- namespaces:
102+
namespaceSelector:
103+
matchLabels:
104+
kubernetes.io/metadata.name: monitoring
105+
# ...
106+
----
107+
====
108+
109+
This example is a strong `Pass` action ANP because it delegates the decision to `NetworkPolicy` objects defined by tenant owners. This `pass-monitoring` ANP allows all tenant owners grouped at security level `internal` to choose if their metrics should be scraped by the infrastructures' monitoring service using namespace scoped `NetworkPolicy` objects.
110+
111+
//We will need to put this in for 4.16 when the module on best practices are created.
112+
//For more information an example of how to use `NetworkPolicy` to create multi-tenancy policies using ANP and BANP, see "BaselineAdminNetworkPolicy multi-tenancy example".

‎modules/nw-ovn-k-adminnetwork-policy.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ovn-k-network-policy.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="adminnetworkpolicy_{context}"]
7+
= AdminNetworkPolicy
8+
9+
An `AdminNetworkPolicy` (ANP) is a cluster-scoped custom resource definition (CRD). As a {product-title} administrator, you can use ANP to secure your network by creating network policies before creating namespaces. Additionally, you can create network policies on a cluster-scoped level that is non-overridable by `NetworkPolicy` objects.
10+
11+
The key difference between `AdminNetworkPolicy` and `NetworkPolicy` objects are that the former is for administrators and is cluster scoped while the latter is for tenant owners and is namespace scoped.
12+
13+
An ANP allows administrators to specify the following:
14+
15+
* A `priority` value that determines the order of its evaluation. The lower the value the higher the precedence.
16+
17+
* A `subject` that consists of a set of namespaces or namespace..
18+
19+
* A list of ingress rules to be applied for all ingress traffic towards the `subject`.
20+
21+
* A list of egress rules to be applied for all egress traffic from the `subject`.
22+
23+
[NOTE]
24+
====
25+
The `AdminNetworkPolicy` resource is a `TechnologyPreviewNoUpgrade` feature that can be enabled on test clusters that are not in production. For more information on feature gates and `TechnologyPreviewNoUpgrade` features, see "Enabling features using feature gates" in the "Additional resources" of this section.
26+
====
27+
28+
[discrete]
29+
[id="adminnetworkpolicy-example_{context}"]
30+
== AdminNetworkPolicy example
31+
32+
.Example YAML file for an ANP
33+
[%collapsible]
34+
====
35+
[source,yaml]
36+
----
37+
apiVersion: policy.networking.k8s.io/v1alpha1
38+
kind: AdminNetworkPolicy
39+
metadata:
40+
name: sample-anp-deny-pass-rules <1>
41+
spec:
42+
priority: 50 <2>
43+
subject:
44+
namespaces:
45+
matchLabels:
46+
kubernetes.io/metadata.name: example.name <3>
47+
ingress: <4>
48+
- name: "deny-all-ingress-tenant-1" <5>
49+
action: "Deny"
50+
from:
51+
- pods:
52+
namespaces: <6>
53+
namespaceSelector:
54+
matchLabels:
55+
custom-anp: tenant-1
56+
podSelector:
57+
matchLabels:
58+
custom-anp: tenant-1 <7>
59+
egress:<8>
60+
- name: "pass-all-egress-to-tenant-1"
61+
action: "Pass"
62+
to:
63+
- pods:
64+
namespaces:
65+
namespaceSelector:
66+
matchLabels:
67+
custom-anp: tenant-1
68+
podSelector:
69+
matchLabels:
70+
custom-anp: tenant-1
71+
----
72+
<1> Specify a name for your ANP.
73+
<2> The `spec.priority` field supports a maximum of 100 ANP in the values of 0-99 in a cluster. The lower the value the higher the precedence. Creating `AdminNetworkPolicy` with the same priority creates a nondeterministic outcome.
74+
<3> Specify the namespace to apply the ANP resource.
75+
<4> ANP have both ingress and egress rules. ANP rules for `spec.ingress` field accepts values of `Pass`, `Deny`, and `Allow` for the `action` field.
76+
<5> Specify a name for the `ingress.name`.
77+
<6> Specify the namespaces to select the pods from to apply the ANP resource.
78+
<7> Specify `podSelector.matchLabels` name of the pods to apply the ANP resource.
79+
<8> ANP have both ingress and egress rules. ANP rules for `spec.egress` field accepts values of `Pass`, `Deny`, and `Allow` for the `action` field.
80+
====

‎modules/nw-ovn-k-baseline-adminnetwork-policy.adoc

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ovn-k-network-policy.adoc
4+
5+
:_mod-docs-content-type: Concept
6+
[id="BaselineAdminNetworkPolicy"_{context}"]
7+
= BaselineAdminNetworkPolicy
8+
9+
`BaselineAdminNetworkPolicy` (BANP) is a cluster-scoped custom resource definition (CRD). As a {product-title} administrator, you can use BANP to setup and enforce optional baseline network policy rules that are overridable by users using `NetworkPolicy` objects if need be. Rule actions for BANP are `allow` or `deny`.
10+
11+
The `BaselineAdminNetworkPolicy` resource is a cluster singleton object that can be used as a guardrail policy incase a passed traffic policy does not match any `NetworkPolicy` objects in the cluster. A BANP can also be used as a default security model that provides guardrails that intra-cluster traffic is blocked by default and a user will need to use `NetworkPolicy` objects to allow known traffic. You must use `default` as the name when creating a BANP resource.
12+
13+
A BANP allows administrators to specify:
14+
15+
* A `subject` that consists of a set of namespaces or namespace.
16+
17+
* A list of ingress rules to be applied for all ingress traffic towards the `subject`.
18+
19+
* A list of egress rules to be applied for all egress traffic from the `subject`.
20+
21+
[NOTE]
22+
====
23+
`BaselineAdminNetworkPolicy` is a `TechnologyPreviewNoUpgrade` feature that can be enabled on test clusters that are not in production.
24+
====
25+
26+
[discrete]
27+
[id="baselineddminnetworkpolicy-example_{context}"]
28+
== BaselineAdminNetworkPolicy example
29+
30+
31+
.Example YAML file for BANP
32+
[%collapsible]
33+
====
34+
[source,yaml]
35+
----
36+
apiVersion: policy.networking.k8s.io/v1alpha1
37+
kind: BaselineAdminNetworkPolicy
38+
metadata:
39+
name: default <1>
40+
spec:
41+
subject:
42+
namespaces:
43+
matchLabels:
44+
kubernetes.io/metadata.name: example.name <2>
45+
ingress: <3>
46+
- name: "deny-all-ingress-from-tenant-1" <4>
47+
action: "Deny"
48+
from:
49+
- pods:
50+
namespaces:
51+
namespaceSelector:
52+
matchLabels:
53+
custom-banp: tenant-1 <5>
54+
podSelector:
55+
matchLabels:
56+
custom-banp: tenant-1 <6>
57+
egress:
58+
- name: "allow-all-egress-to-tenant-1"
59+
action: "Allow"
60+
to:
61+
- pods:
62+
namespaces:
63+
namespaceSelector:
64+
matchLabels:
65+
custom-banp: tenant-1
66+
podSelector:
67+
matchLabels:
68+
custom-banp: tenant-1
69+
----
70+
<1> The policy name must be `default` because BANP is a singleton object.
71+
<2> Specify the namespace to apply the ANP to.
72+
<3> BANP have both ingress and egress rules. BANP rules for `spec.ingress` and `spec.egress` fields accepts values of `Deny` and `Allow` for the `action` field.
73+
<4> Specify a name for the `ingress.name`
74+
<5> Specify the namespaces to select the pods from to apply the BANP resource.
75+
<6> Specify `podSelector.matchLabels` name of the pods to apply the BANP resource.
76+
====
77+
78+
79+
[discrete]
80+
[id="BaselineAdminNetworkPolicy-default-deny-example"_{context}]
81+
== BaselineAdminNetworkPolicy Deny example
82+
The following BANP singleton ensures that the administrator has set up a default deny policy for all ingress monitoring traffic coming into the tenants at `internal` security level. When combined with the "AdminNetworkPolicy Pass example", this deny policy acts as a guardrail policy for all ingress traffic that is passed by the ANP `pass-monitoring` policy.
83+
84+
.Example YAML file for a guardrail `Deny` rule
85+
[%collapsible]
86+
====
87+
[source,yaml]
88+
----
89+
apiVersion: policy.networking.k8s.io/v1alpha1
90+
kind: BaselineAdminNetworkPolicy
91+
metadata:
92+
name: default
93+
spec:
94+
subject:
95+
namespaces:
96+
matchLabels:
97+
security: internal
98+
ingress:
99+
- name: "deny-ingress-from-monitoring"
100+
action: "Deny"
101+
from:
102+
- namespaces:
103+
namespaceSelector:
104+
matchLabels:
105+
kubernetes.io/metadata.name: monitoring
106+
# ...
107+
----
108+
====
109+
110+
You can use an `AdminNetworkPolicy` resource with a `Pass` value for the `action` field in conjunction with the `BaselineAdminNetworkPolicy` resource to create a multi-tenant policy. This multi-tenant policy allows one tenant to collect monitoring data on their application while simultaneously not collecting data from a second tenant.
111+
112+
As an administrator, if you apply both the "AdminNetworkPolicy `Pass` action example" and the "BaselineAdminNetwork Policy `Deny` example", tenants are then left with the ability to choose to create a `NetworkPolicy` resource that will be evaluated before the BANP.
113+
114+
For example, Tenant 1 can set up the following `NetworkPolicy` resource to monitor ingress traffic:
115+
116+
.Example `NetworkPolicy`
117+
[%collapsible]
118+
====
119+
[source,yaml]
120+
----
121+
apiVersion: networking.k8s.io/v1
122+
kind: NetworkPolicy
123+
metadata:
124+
name: allow-monitoring
125+
namespace: tenant 1
126+
spec:
127+
podSelector:
128+
policyTypes:
129+
- Ingress
130+
ingress:
131+
- from:
132+
- namespaceSelector:
133+
matchLabels:
134+
kubernetes.io/metadata.name: monitoring
135+
# ...
136+
----
137+
====
138+
139+
In this scenario, Tenant 1's policy would be evaluated after the "AdminNetworkPolicy `Pass` action example" and before the "BaselineAdminNetwork Policy `Deny` example", which denies all ingress monitoring traffic coming into tenants with `security` level `internal`. With Tenant 1's `NetworkPolicy` object in place, they will be able to collect data on their application. Tenant 2, however, who does not have any `NetworkPolicy` objects in place, will not be able to collect data. As an administrator, you have not by default monitored internal tenants, but instead, you created a BANP that allows tenants to use `NetworkPolicy` objects to override the default behavior of your BANP.
140+

‎networking/ovn_kubernetes_network_provider/ovn-k-network-policy.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ovn-k-network-policy"]
3+
= OVN-Kubernetes network policy
4+
include::_attributes/common-attributes.adoc[]
5+
:context: ovn-k-network-policy
6+
7+
toc::[]
8+
9+
:FeatureName: The `AdminNetworkPolicy` resource
10+
include::snippets/technology-preview.adoc[]
11+
12+
Kubernetes offers two features that users can use to enforce network security. One feature that allows users to enforce network policy is the `NetworkPolicy` API that is designed mainly for application developers and namespace tenants to protect their namespaces by creating namespace-scoped policies. For more information, see xref:../../networking/network_policy/about-network-policy.adoc#nw-networkpolicy-about_about-network-policy[About network policy].
13+
14+
The second feature is `AdminNetworkPolicy` which is comprised of two API: the `AdminNetworkPolicy` (ANP) API and the `BaselineAdminNetworkPolicy` (BANP) API. ANP and BANP are designed for cluster and network administrators to protect their entire cluster by creating cluster-scoped policies. Cluster administrators can use ANPs to enforce non-overridable policies that take precedence over `NetworkPolicy` objects. Administrators can use BANP to setup and enforce optional cluster-scoped network policy rules that are overridable by users using `NetworkPolicy` objects if need be. When used together ANP and BANP can create multi-tenancy policy that administrators can use to secure their cluster.
15+
16+
OVN-Kubernetes CNI in {product-title} implements these network policies using Access Control List (ACLs) Tiers to evaluate and apply them. ACLs are evaluated in descending order from Tier 1 to Tier 3.
17+
18+
Tier 1 evaluates `AdminNetworkPolicy` (ANP) objects. Tier 2 evaluates `NetworkPolicy` objects. Tier 3 evaluates `BaselineAdminNetworkPolicy` (BANP) objects.
19+
20+
// <image here to help describe ACLs>
21+
22+
If traffic matches an ANP rule, the rules in that ANP will be evaluated first. If the match is an ANP `allow` or `deny` rule, any existing `NetworkPolicies` and `BaselineAdminNetworkPolicy` (BANP) in the cluster will be intentionally skipped from evaluation. If the match is an ANP `pass` rule, then evaluation moves from tier 1 of the ACLs to tier 2 where the `NetworkPolicy` policy is evaluated.
23+
24+
include::modules/nw-ovn-k-adminnetwork-policy.adoc[leveloffset=+1]
25+
26+
[discrete]
27+
.Additional resources
28+
* xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling features using feature gates]
29+
* link:https://network-policy-api.sigs.k8s.io/[Network Policy API Working Group]
30+
31+
include::modules/nw-ovn-k-adminnetwork-policy-action-rules.adoc[leveloffset=+2]
32+
33+
include::modules/nw-ovn-k-baseline-adminnetwork-policy.adoc[leveloffset=+1]
34+
35+
36+
37+

0 commit comments

Comments
 (0)