Skip to content

Commit 8af0a48

Browse files
jboxmanjboxman
authored
Merge pull request #33386 from jboxman/OSDOCS-1967
OSDOCS-1967: Add network policy audit logging
2 parents 9bb002e + 918f2ca commit 8af0a48

File tree

9 files changed

+479
-0
lines changed

9 files changed

+479
-0
lines changed

‎_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -870,6 +870,8 @@ Topics:
870870
Topics:
871871
- Name: About network policy
872872
File: about-network-policy
873+
- Name: Logging network policy
874+
File: logging-network-policy
873875
- Name: Creating a network policy
874876
File: creating-network-policy
875877
- Name: Viewing a network policy

‎modules/nw-networkpolicy-audit-concept.adoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[id="nw-networkpolicy-audit-concept_{context}"]
2+
= Network policy audit logging
3+
4+
The OVN-Kubernetes cluster network provider uses Open Virtual Network (OVN) ACLs to manage network policy. Audit logging exposes allow and deny ACL events.
5+
6+
You can configure the destination for network policy audit logs, such as a syslog server or a UNIX domain socket.
7+
Regardless of any additional configuration, an audit log is always saved to `/var/log/ovn/acl-audit-log.log` on each OVN-Kubernetes pod in the cluster.
8+
9+
Network policy audit logging is enabled per namespace by annotating the namespace with the `k8s.ovn.org/acl-logging` key as in the following example:
10+
11+
.Example namespace annotation
12+
[source,yaml]
13+
----
14+
kind: Namespace
15+
apiVersion: v1
16+
metadata:
17+
name: example1
18+
annotations:
19+
k8s.ovn.org/acl-logging: |-
20+
{
21+
"deny": "info",
22+
"allow": "info"
23+
}
24+
----
25+
26+
The logging format is compatible with syslog as defined by RFC5424. The syslog facility is configurable and defaults to `local0`. An example log entry might resemble the following:
27+
28+
.Example ACL deny log entry
29+
[source,text]
30+
----
31+
2021-06-13T19:33:11.590Z|00005|acl_log(ovn_pinctrl0)|INFO|name="verify-audit-logging_deny-all", verdict=drop, severity=alert: icmp,vlan_tci=0x0000,dl_src=0a:58:0a:80:02:39,dl_dst=0a:58:0a:80:02:37,nw_src=10.128.2.57,nw_dst=10.128.2.55,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,icmp_code=0
32+
----
33+
34+
The following table describes namespace annotation values:
35+
36+
.Network policy audit logging namespace annotation
37+
[cols=".^4,.^6a",options="header"]
38+
|====
39+
|Annotation|Value
40+
41+
|`k8s.ovn.org/acl-logging`
42+
|
43+
You must specify at least one of `allow`, `deny`, or both to enable network policy audit logging for a namespace.
44+
45+
`deny`:: Optional: Specify `alert`, `warning`, `notice`, `info`, or `debug`.
46+
`allow`:: Optional: Specify `alert`, `warning`, `notice`, `info`, or `debug`.
47+
48+
|====

‎modules/nw-networkpolicy-audit-configure.adoc‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
[id="nw-networkpolicy-audit-configure_{context}"]
2+
= Configuring network policy auditing for a cluster
3+
4+
As a cluster administrator, you can customize network policy audit logging for your cluster.
5+
6+
.Prerequisites
7+
8+
* Install the OpenShift CLI (`oc`).
9+
* Log in to the cluster with a user with `cluster-admin` privileges.
10+
11+
.Procedure
12+
13+
* To customize the network policy audit logging configuration, enter the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc edit network.operator.openshift.io/cluster
18+
----
19+
+
20+
[TIP]
21+
====
22+
You can alternatively customize and apply the following YAML to configure audit logging:
23+
24+
[source,yaml]
25+
----
26+
apiVersion: operator.openshift.io/v1
27+
kind: Network
28+
metadata:
29+
name: cluster
30+
spec:
31+
defaultNetwork:
32+
ovnKubernetesConfig:
33+
policyAuditConfig:
34+
destination: "null"
35+
maxFileSize: 50
36+
rateLimit: 20
37+
syslogFacility: local0
38+
----
39+
====
40+
41+
.Verification
42+
43+
. To create a namespace with network policies complete the following steps:
44+
.. Create a namespace for verification:
45+
+
46+
[source,terminal]
47+
----
48+
$ cat <<EOF| oc create -f -
49+
kind: Namespace
50+
apiVersion: v1
51+
metadata:
52+
name: verify-audit-logging
53+
annotations:
54+
k8s.ovn.org/acl-logging: '{ "deny": "alert", "allow": "alert" }'
55+
EOF
56+
----
57+
+
58+
.Example output
59+
[source,text]
60+
----
61+
namespace/verify-audit-logging created
62+
----
63+
64+
.. Enable audit logging:
65+
+
66+
[source,terminal]
67+
----
68+
$ oc annotate namespace verify-audit-logging k8s.ovn.org/acl-logging='{ "deny": "alert", "allow": "alert" }'
69+
----
70+
+
71+
[source,text]
72+
----
73+
namespace/verify-audit-logging annotated
74+
----
75+
76+
.. Create network policies for the namespace:
77+
+
78+
[source,terminal]
79+
----
80+
$ cat <<EOF| oc create -n verify-audit-logging -f -
81+
apiVersion: networking.k8s.io/v1
82+
kind: NetworkPolicy
83+
metadata:
84+
name: deny-all
85+
spec:
86+
podSelector:
87+
matchLabels:
88+
policyTypes:
89+
- Ingress
90+
- Egress
91+
---
92+
apiVersion: networking.k8s.io/v1
93+
kind: NetworkPolicy
94+
metadata:
95+
name: allow-from-same-namespace
96+
spec:
97+
podSelector: {}
98+
policyTypes:
99+
- Ingress
100+
- Egress
101+
ingress:
102+
- from:
103+
- podSelector: {}
104+
egress:
105+
- to:
106+
- namespaceSelector:
107+
matchLabels:
108+
namespace: verify-audit-logging
109+
EOF
110+
----
111+
+
112+
.Example output
113+
[source,text]
114+
----
115+
networkpolicy.networking.k8s.io/deny-all created
116+
networkpolicy.networking.k8s.io/allow-from-same-namespace created
117+
----
118+
119+
. Create a pod for source traffic in the `default` namespace:
120+
+
121+
[source,terminal]
122+
----
123+
$ cat <<EOF| oc create -n default -f -
124+
apiVersion: v1
125+
kind: Pod
126+
metadata:
127+
name: client
128+
spec:
129+
containers:
130+
- name: client
131+
image: registry.access.redhat.com/rhel7/rhel-tools
132+
command: ["/bin/sh", "-c"]
133+
args:
134+
["sleep inf"]
135+
EOF
136+
----
137+
138+
. Create two pods in the `verify-audit-logging` namespace:
139+
+
140+
[source,terminal]
141+
----
142+
$ for name in client server; do
143+
cat <<EOF| oc create -n verify-audit-logging -f -
144+
apiVersion: v1
145+
kind: Pod
146+
metadata:
147+
name: ${name}
148+
spec:
149+
containers:
150+
- name: ${name}
151+
image: registry.access.redhat.com/rhel7/rhel-tools
152+
command: ["/bin/sh", "-c"]
153+
args:
154+
["sleep inf"]
155+
EOF
156+
done
157+
----
158+
+
159+
.Example output
160+
[source,text]
161+
----
162+
pod/client created
163+
pod/server created
164+
----
165+
166+
. To generate traffic and produce network policy audit log entries, complete the following steps:
167+
168+
.. Obtain the IP address for pod named `server` in the `verify-audit-logging` namespace:
169+
+
170+
[source,terminal]
171+
----
172+
$ POD_IP=$(oc get pods server -n verify-audit-logging -o jsonpath='{.status.podIP}')
173+
----
174+
175+
.. Ping the IP address from the previous command from the pod named `client` in the `default` namespace and confirm that all packets are dropped:
176+
+
177+
[source,terminal]
178+
----
179+
$ oc exec -it client -n default -- /bin/ping -c 2 $POD_IP
180+
----
181+
+
182+
.Example output
183+
[source,text]
184+
----
185+
PING 10.128.2.55 (10.128.2.55) 56(84) bytes of data.
186+
187+
--- 10.128.2.55 ping statistics ---
188+
2 packets transmitted, 0 received, 100% packet loss, time 2041ms
189+
----
190+
191+
.. Ping the IP address saved in the `POD_IP` shell environment variable from the pod named `client` in the `verify-audit-logging` namespace and confirm that all packets are allowed:
192+
+
193+
[source,terminal]
194+
----
195+
$ oc exec -it client -n verify-audit-logging -- /bin/ping -c 2 $POD_IP
196+
----
197+
+
198+
.Example output
199+
[source,text]
200+
----
201+
PING 10.128.0.86 (10.128.0.86) 56(84) bytes of data.
202+
64 bytes from 10.128.0.86: icmp_seq=1 ttl=64 time=2.21 ms
203+
64 bytes from 10.128.0.86: icmp_seq=2 ttl=64 time=0.440 ms
204+
205+
--- 10.128.0.86 ping statistics ---
206+
2 packets transmitted, 2 received, 0% packet loss, time 1001ms
207+
rtt min/avg/max/mdev = 0.440/1.329/2.219/0.890 ms
208+
----
209+
210+
. Display the latest entries in the network policy audit log:
211+
+
212+
[source,terminal]
213+
----
214+
$ for pod in $(oc get pods -n openshift-ovn-kubernetes -l app=ovnkube-node --no-headers=true | awk '{ print $1 }') ; do
215+
oc exec -it $pod -n openshift-ovn-kubernetes -- tail -4 /var/log/ovn/acl-audit-log.log
216+
done
217+
----
218+
+
219+
.Example output
220+
[source,text]
221+
----
222+
Defaulting container name to ovn-controller.
223+
Use 'oc describe pod/ovnkube-node-hdb8v -n openshift-ovn-kubernetes' to see all of the containers in this pod.
224+
2021-06-13T19:33:11.590Z|00005|acl_log(ovn_pinctrl0)|INFO|name="verify-audit-logging_deny-all", verdict=drop, severity=alert: icmp,vlan_tci=0x0000,dl_src=0a:58:0a:80:02:39,dl_dst=0a:58:0a:80:02:37,nw_src=10.128.2.57,nw_dst=10.128.2.55,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,icmp_code=0
225+
2021-06-13T19:33:12.614Z|00006|acl_log(ovn_pinctrl0)|INFO|name="verify-audit-logging_deny-all", verdict=drop, severity=alert: icmp,vlan_tci=0x0000,dl_src=0a:58:0a:80:02:39,dl_dst=0a:58:0a:80:02:37,nw_src=10.128.2.57,nw_dst=10.128.2.55,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,icmp_code=0
226+
2021-06-13T19:44:10.037Z|00007|acl_log(ovn_pinctrl0)|INFO|name="verify-audit-logging_allow-from-same-namespace_0", verdict=allow, severity=alert: icmp,vlan_tci=0x0000,dl_src=0a:58:0a:80:02:3b,dl_dst=0a:58:0a:80:02:3a,nw_src=10.128.2.59,nw_dst=10.128.2.58,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,icmp_code=0
227+
2021-06-13T19:44:11.037Z|00008|acl_log(ovn_pinctrl0)|INFO|name="verify-audit-logging_allow-from-same-namespace_0", verdict=allow, severity=alert: icmp,vlan_tci=0x0000,dl_src=0a:58:0a:80:02:3b,dl_dst=0a:58:0a:80:02:3a,nw_src=10.128.2.59,nw_dst=10.128.2.58,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,icmp_code=0
228+
----

‎modules/nw-networkpolicy-audit-disable.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[id="nw-networkpolicy-audit-disable_{context}"]
2+
= Disabling network policy audit logging for a namespace
3+
4+
As a cluster administrator, you can disable network policy audit logging for a namespace.
5+
6+
.Prerequisites
7+
8+
* Install the OpenShift CLI (`oc`).
9+
* Log in to the cluster with a user with `cluster-admin` privileges.
10+
11+
.Procedure
12+
13+
* To disable network policy audit logging for a namespace, enter the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ annotate --overwrite namespace <namespace> k8s.ovn.org/acl-logging={}
18+
----
19+
+
20+
--
21+
where:
22+
23+
`<namespace>`:: Specifies the name of the namespace.
24+
--
25+
+
26+
[TIP]
27+
====
28+
You can alternatively apply the following YAML to disable audit logging:
29+
30+
[source,yaml]
31+
----
32+
kind: Namespace
33+
apiVersion: v1
34+
metadata:
35+
name: <namespace>
36+
annotations:
37+
k8s.ovn.org/acl-logging: null
38+
----
39+
====
40+
+
41+
.Example output
42+
[source,terminal]
43+
----
44+
namespace/verify-audit-logging annotated
45+
----

0 commit comments

Comments
 (0)