Skip to content

Commit 7a4cc74

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #157 from huntergregory/bump-cyc-to-v0.5.5
chore: bump Cyclonus to v0.5.5
2 parents 262dc04 + cbf13c9 commit 7a4cc74

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1095
-1035
lines changed

‎cmd/cyclonus/cmd/worker/Dockerfile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
FROM registry.k8s.io/e2e-test-images/agnhost:2.36
1+
FROM registry.k8s.io/e2e-test-images/agnhost:2.43
22

33
ENTRYPOINT ["/worker"]
44

‎cmd/cyclonus/docs/command-analyze.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# cyclonus analyze
2+
3+
The `analyze` command provides a suite of tools for understanding and poking network policies,
4+
without the need for a working kubernetes cluster or CNI.
5+
6+
It provides several modes which can be activated by a `--mode $MODE` flag. Multiple `--mode`
7+
flags may be provided in a single invocation.
8+
9+
## Supported flags
10+
11+
```bash
12+
cyclonus analyze -h
13+
analyze network policies
14+
15+
Usage:
16+
cyclonus analyze [flags]
17+
18+
Flags:
19+
-A, --all-namespaces reads kube resources from all namespaces; same as kubectl's '--all-namespaces'/'-A' flag
20+
--context string selects kube context to read policies from; only reads from kube if one or more namespaces or all namespaces are specified
21+
-h, --help help for analyze
22+
--mode strings analysis modes to run; allowed values are parse,explain,lint,query-traffic,query-target,probe (default [explain])
23+
-n, --namespace strings namespaces to read kube resources from; similar to kubectl's '--namespace'/'-n' flag, except that multiple namespaces may be passed in and is empty if not set explicitly (instead of 'default' as in kubectl)
24+
--policy-path string may be a file or a directory; if set, will attempt to read policies from the path
25+
--probe-path string path to json model file for synthetic probe
26+
--simplify-policies if true, reduce policies to simpler form while preserving semantics (default true)
27+
--target-pod-path string path to json target pod file -- json array of dicts
28+
--traffic-path string path to json traffic file, containing of a list of traffic objects
29+
--use-example-policies if true, reads example policies
30+
31+
Global Flags:
32+
-v, --verbosity string log level; one of [info, debug, trace, warn, error, fatal, panic] (default "info")
33+
```
34+
35+
## Mode examples
36+
37+
### `--mode explain`: explains network policies
38+
39+
Groups policies by target, divides rules into egress and ingress, and gives a basic explanation of the combined
40+
policies. This clarifies the interactions between "denies" and "allows" from multiple policies.
41+
42+
```
43+
cyclonus analyze \
44+
--mode explain \
45+
--policy-path ./networkpolicies/simple-example/
46+
47+
+---------+---------------+------------------------+---------------------+--------------------------+
48+
| TYPE | TARGET | SOURCE RULES | PEER | PORT/PROTOCOL |
49+
+---------+---------------+------------------------+---------------------+--------------------------+
50+
| Ingress | namespace: y | y/allow-label-to-label | no ips | no ports, no protocols |
51+
| | Match labels: | y/deny-all-for-label | | |
52+
| | pod: a | | | |
53+
+ + + +---------------------+--------------------------+
54+
| | | | namespace: y | all ports, all protocols |
55+
| | | | pods: Match labels: | |
56+
| | | | pod: c | |
57+
+ +---------------+------------------------+---------------------+ +
58+
| | namespace: y | y/allow-all-for-label | all pods, all ips | |
59+
| | Match labels: | | | |
60+
| | pod: b | | | |
61+
+ +---------------+------------------------+---------------------+--------------------------+
62+
| | namespace: y | y/allow-by-ip | ports for all IPs | no ports, no protocols |
63+
| | Match labels: | | | |
64+
| | pod: c | | | |
65+
+ + + +---------------------+--------------------------+
66+
| | | | 0.0.0.0/24 | all ports, all protocols |
67+
| | | | except [] | |
68+
| | | | | |
69+
+ + + +---------------------+--------------------------+
70+
| | | | no pods | no ports, no protocols |
71+
| | | | | |
72+
| | | | | |
73+
+ +---------------+------------------------+---------------------+ +
74+
| | namespace: y | y/deny-all | no pods, no ips | |
75+
| | all pods | | | |
76+
+---------+---------------+------------------------+---------------------+--------------------------+
77+
```
78+
79+
### `--mode query-target`: which policy rules apply to a pod?
80+
81+
This takes the previous command a step further: it combines the rules from all the targets that apply
82+
to a pod.
83+
84+
```
85+
cyclonus analyze \
86+
--mode query-target \
87+
--policy-path ./networkpolicies/simple-example/ \
88+
--target-pod-path ./examples/targets.json
89+
90+
pod in ns y with labels map[pod:a]:
91+
+---------+---------------+-----------------------------+---------------------+--------------------------+
92+
| TYPE | TARGET | SOURCE RULES | PEER | PORT/PROTOCOL |
93+
+---------+---------------+-----------------------------+---------------------+--------------------------+
94+
| Ingress | namespace: y | y/allow-label-to-label | no ips | no ports, no protocols |
95+
| | Match labels: | y/deny-all-for-label | | |
96+
| | pod: a | y/deny-all | | |
97+
+ + + +---------------------+--------------------------+
98+
| | | | namespace: y | all ports, all protocols |
99+
| | | | pods: Match labels: | |
100+
| | | | pod: c | |
101+
+---------+---------------+-----------------------------+---------------------+--------------------------+
102+
| | | | | |
103+
+---------+---------------+-----------------------------+---------------------+--------------------------+
104+
| Egress | namespace: y | y/deny-all-egress | all pods, all ips | all ports, all protocols |
105+
| | Match labels: | y/allow-all-egress-by-label | | |
106+
| | pod: a | | | |
107+
+---------+---------------+-----------------------------+---------------------+--------------------------+
108+
```
109+
110+
111+
### `--mode query-traffic`: will policies allow or block traffic?
112+
113+
Given arbitrary traffic examples (from a source to a destination, including labels, over a port and protocol),
114+
this command parses network policies and determines if the traffic is allowed or not.
115+
116+
```
117+
cyclonus analyze \
118+
--mode query-traffic \
119+
--policy-path ./networkpolicies/simple-example/ \
120+
--traffic-path ./examples/traffic.json
121+
122+
Traffic:
123+
+--------------------------+-------------+---------------+-----------+-----------+------------+
124+
| PORT/PROTOCOL | SOURCE/DEST | POD IP | NAMESPACE | NS LABELS | POD LABELS |
125+
+--------------------------+-------------+---------------+-----------+-----------+------------+
126+
| 80 (serve-80-tcp) on TCP | source | 192.168.1.99 | y | ns: y | app: c |
127+
+ +-------------+---------------+ + +------------+
128+
| | destination | 192.168.1.100 | | | pod: b |
129+
+--------------------------+-------------+---------------+-----------+-----------+------------+
130+
131+
Is traffic allowed?
132+
+-------------+--------+---------------+
133+
| TYPE | ACTION | TARGET |
134+
+-------------+--------+---------------+
135+
| Ingress | Allow | namespace: y |
136+
| | | Match labels: |
137+
| | | pod: b |
138+
+ +--------+---------------+
139+
| | Deny | namespace: y |
140+
| | | all pods |
141+
+-------------+--------+---------------+
142+
| | | |
143+
+-------------+--------+---------------+
144+
| Egress | Deny | namespace: y |
145+
| | | all pods |
146+
+-------------+--------+---------------+
147+
| IS ALLOWED? | FALSE |
148+
+-------------+--------+---------------+
149+
```
150+
151+
### `--mode probe`: simulates a connectivity probe
152+
153+
Runs a simulated connectivity probe against a set of network policies, without using a kubernetes cluster.
154+
155+
```
156+
cyclonus analyze \
157+
--mode probe \
158+
--policy-path ./networkpolicies/simple-example/ \
159+
--probe-path ./examples/probe.json
160+
161+
Combined:
162+
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
163+
| | X/A | X/B | X/C | Y/A | Y/B | Y/C | Z/A | Z/B | Z/C |
164+
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
165+
| x/a | . | . | . | X | . | X | . | . | . |
166+
| x/b | . | . | . | X | . | X | . | . | . |
167+
| x/c | . | . | . | X | . | X | . | . | . |
168+
| y/a | . | . | . | X | . | X | . | . | . |
169+
| y/b | . | . | . | X | . | X | . | . | . |
170+
| y/c | X | X | X | X | X | X | X | X | X |
171+
| z/a | . | . | . | X | . | X | . | . | . |
172+
| z/b | . | . | . | X | . | X | . | . | . |
173+
| z/c | . | . | . | X | . | X | . | . | . |
174+
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
175+
```
176+
177+
### `--mode lint`: lints network policies
178+
179+
Checks network policies for common problems.
180+
181+
```
182+
cyclonus analyze \
183+
--mode lint \
184+
--policy-path ./networkpolicies/simple-example
185+
186+
+-----------------+------------------------------+-------------------+-----------------------------+
187+
| SOURCE/RESOLVED | TYPE | TARGET | SOURCE POLICIES |
188+
+-----------------+------------------------------+-------------------+-----------------------------+
189+
| Resolved | CheckTargetAllEgressAllowed | namespace: y | y/allow-all-egress-by-label |
190+
| | | | |
191+
| | | pod selector: | |
192+
| | | matchExpressions: | |
193+
| | | - key: pod | |
194+
| | | operator: In | |
195+
| | | values: | |
196+
| | | - a | |
197+
| | | - b | |
198+
| | | | |
199+
+-----------------+------------------------------+-------------------+-----------------------------+
200+
| Resolved | CheckDNSBlockedOnTCP | namespace: y | y/deny-all-egress |
201+
| | | | |
202+
| | | pod selector: | |
203+
| | | {} | |
204+
| | | | |
205+
+-----------------+------------------------------+-------------------+-----------------------------+
206+
| Resolved | CheckDNSBlockedOnUDP | namespace: y | y/deny-all-egress |
207+
| | | | |
208+
| | | pod selector: | |
209+
| | | {} | |
210+
| | | | |
211+
+-----------------+------------------------------+-------------------+-----------------------------+
212+
```

‎cmd/cyclonus/docs/command-generate.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# cyclonus generate
2+
3+
For CNI conformance testing.
4+
5+
Generate network policy test scenarios, install the scenarios one at a time in kubernetes,
6+
and compare actual measured connectivity to expected connectivity using a truth table.
7+
8+
## Supported flags
9+
10+
```bash
11+
generate network policies, create and probe against kubernetes, and compare to expected results
12+
13+
Usage:
14+
cyclonus generate [flags]
15+
16+
Flags:
17+
--allow-dns if using egress, allow tcp and udp over port 53 for DNS resolution (default true)
18+
--cleanup-namespaces if true, clean up namespaces after completion
19+
--context string kubernetes context to use; if empty, uses default context
20+
--destination-type string override to set what to direct requests at; if not specified, the tests will be left as-is; one of service-name, service-ip, pod-ip
21+
--dry-run if true, don't actually do anything: just print out what would be done
22+
--exclude strings exclude tests with any of these tags. See 'include' field for valid tags (default [multi-peer,upstream-e2e,example,end-port])
23+
-h, --help help for generate
24+
--ignore-loopback if true, ignore loopback for truthtable correctness verification
25+
--include strings include tests with any of these tags; if empty, all tests will be included.
26+
--job-timeout-seconds int number of seconds to pass on to 'agnhost connect --timeout=%ds' flag (default 10)
27+
--junit-results-file string output junit results to the specified file
28+
--mock if true, use a mock kube runner (i.e. don't actually run tests against kubernetes; instead, product fake results
29+
--namespace strings namespaces to create/use pods in (default [x,y,z])
30+
--noisy if true, print all results
31+
--perturbation-wait-seconds int number of seconds to wait after perturbing the cluster (i.e. create a network policy, modify a ns/pod label) before running probes, to give the CNI time to update the cluster state (default 5)
32+
--pod strings pods to create in namespaces (default [a,b,c])
33+
--pod-creation-timeout-seconds int number of seconds to wait for pods to create, be running and have IP addresses (default 60)
34+
--retries int number of kube probe retries to allow, if probe fails (default 1)
35+
--server-port ints ports to run server on (default [80,81])
36+
--server-protocol strings protocols to run server on (default [TCP,UDP,SCTP])
37+
38+
Global Flags:
39+
-v, --verbosity string log level; one of [info, debug, trace, warn, error, fatal, panic] (default "info")
40+
```
41+
42+
## Example
43+
44+
```
45+
cyclonus generate \
46+
--mode simple-fragments \
47+
--include conflict,peer-ipblock \
48+
--ignore-loopback \
49+
--perturbation-wait-seconds 15
50+
51+
...
52+
Tag results:
53+
```
54+
| Tag | Result |
55+
| --- | --- |
56+
| direction | 10 / 20 = 50% ❌ |
57+
| - egress | 5 / 11 = 45% ❌ |
58+
| - ingress | 5 / 11 = 45% ❌ |
59+
| miscellaneous | 10 / 16 = 62% ❌ |
60+
| - conflict | 10 / 16 = 62% ❌ |
61+
| peer-ipblock | 0 / 4 = 0% ❌ |
62+
| - IP-block-no-except | 0 / 2 = 0% ❌ |
63+
| - IP-block-with-except | 0 / 2 = 0% ❌ |
64+
| peer-pods | 4 / 4 = 100% ✅ |
65+
| - all-namespaces | 4 / 4 = 100% ✅ |
66+
| - all-pods | 4 / 4 = 100% ✅ |
67+
| rule | 6 / 8 = 75% ❌ |
68+
| - allow-all | 2 / 4 = 50% ❌ |
69+
| - deny-all | 6 / 8 = 75% ❌ |

0 commit comments

Comments
 (0)