Skip to content

Commit 845ce8b

Browse files
mattfenwickmattfenwick
committed
organize docs
1 parent 2c3c13d commit 845ce8b

File tree

4 files changed

+347
-241
lines changed

4 files changed

+347
-241
lines changed

‎README.md

+4-241
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ Images are available at [mfenwick100/cyclonus](https://hub.docker.com/r/mfenwick
8686
docker pull docker.io/mfenwick100/cyclonus:latest
8787
```
8888

89+
8990
## Integrations
9091

9192
### krew plugin
@@ -107,248 +108,10 @@ Cyclonus is available as a [krew/kubectl plugin](https://github.com/mattfenwick/
107108

108109
## Cyclonus functionality
109110

110-
### Probe
111-
112-
Run a connectivity probe against a Kubernetes cluster.
113-
114-
```
115-
cyclonus probe
116-
117-
Kube results for:
118-
policy y/allow-all-for-label:
119-
policy y/allow-by-ip:
120-
policy y/allow-label-to-label:
121-
policy y/deny-all:
122-
policy y/deny-all-for-label:
123-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
124-
| - | X/A | X/B | X/C | Y/A | Y/B | Y/C | Z/A | Z/B | Z/C |
125-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
126-
| x/a | . | . | . | X | . | X | . | . | . |
127-
| x/b | . | . | . | X | . | X | . | . | . |
128-
| x/c | . | . | . | X | . | X | . | . | . |
129-
| y/a | . | . | . | X | . | X | . | . | . |
130-
| y/b | . | . | . | X | . | X | . | . | . |
131-
| y/c | . | . | . | . | . | X | . | . | . |
132-
| z/a | . | . | . | X | . | X | . | . | . |
133-
| z/b | . | . | . | X | . | X | . | . | . |
134-
| z/c | . | . | . | X | . | X | . | . | . |
135-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
136-
137-
0 wrong, 0 no value, 81 correct, 0 ignored out of 81 total
138-
```
139-
140-
### Policy generator
141-
142-
For CNI conformance testing.
143-
144-
Generate network policy test scenarios, install the scenarios one at a time in kubernetes,
145-
and compare actual measured connectivity to expected connectivity using a truth table.
146-
147-
```
148-
cyclonus generate \
149-
--mode simple-fragments \
150-
--include conflict,peer-ipblock \
151-
--ignore-loopback \
152-
--perturbation-wait-seconds 15
153-
154-
...
155-
Tag results:
156-
```
157-
| Tag | Result |
158-
| --- | --- |
159-
| direction | 10 / 20 = 50% ❌ |
160-
| - egress | 5 / 11 = 45% ❌ |
161-
| - ingress | 5 / 11 = 45% ❌ |
162-
| miscellaneous | 10 / 16 = 62% ❌ |
163-
| - conflict | 10 / 16 = 62% ❌ |
164-
| peer-ipblock | 0 / 4 = 0% ❌ |
165-
| - IP-block-no-except | 0 / 2 = 0% ❌ |
166-
| - IP-block-with-except | 0 / 2 = 0% ❌ |
167-
| peer-pods | 4 / 4 = 100% ✅ |
168-
| - all-namespaces | 4 / 4 = 100% ✅ |
169-
| - all-pods | 4 / 4 = 100% ✅ |
170-
| rule | 6 / 8 = 75% ❌ |
171-
| - allow-all | 2 / 4 = 50% ❌ |
172-
| - deny-all | 6 / 8 = 75% ❌ |
173-
174-
### Policy analysis
175-
176-
#### Explain policies
177-
178-
Groups policies by target, divides rules into egress and ingress, and gives a basic explanation of the combined
179-
policies. This clarifies the interactions between "denies" and "allows" from multiple policies.
180-
181-
```
182-
cyclonus analyze \
183-
--mode explain \
184-
--policy-path ./networkpolicies/simple-example/
185-
186-
+---------+---------------+------------------------+---------------------+--------------------------+
187-
| TYPE | TARGET | SOURCE RULES | PEER | PORT/PROTOCOL |
188-
+---------+---------------+------------------------+---------------------+--------------------------+
189-
| Ingress | namespace: y | y/allow-label-to-label | no ips | no ports, no protocols |
190-
| | Match labels: | y/deny-all-for-label | | |
191-
| | pod: a | | | |
192-
+ + + +---------------------+--------------------------+
193-
| | | | namespace: y | all ports, all protocols |
194-
| | | | pods: Match labels: | |
195-
| | | | pod: c | |
196-
+ +---------------+------------------------+---------------------+ +
197-
| | namespace: y | y/allow-all-for-label | all pods, all ips | |
198-
| | Match labels: | | | |
199-
| | pod: b | | | |
200-
+ +---------------+------------------------+---------------------+--------------------------+
201-
| | namespace: y | y/allow-by-ip | ports for all IPs | no ports, no protocols |
202-
| | Match labels: | | | |
203-
| | pod: c | | | |
204-
+ + + +---------------------+--------------------------+
205-
| | | | 0.0.0.0/24 | all ports, all protocols |
206-
| | | | except [] | |
207-
| | | | | |
208-
+ + + +---------------------+--------------------------+
209-
| | | | no pods | no ports, no protocols |
210-
| | | | | |
211-
| | | | | |
212-
+ +---------------+------------------------+---------------------+ +
213-
| | namespace: y | y/deny-all | no pods, no ips | |
214-
| | all pods | | | |
215-
+---------+---------------+------------------------+---------------------+--------------------------+
216-
```
217-
218-
#### Which policy rules apply to a pod?
219-
220-
This takes the previous command a step further: it combines the rules from all the targets that apply
221-
to a pod.
222-
223-
```
224-
cyclonus analyze \
225-
--mode query-target \
226-
--policy-path ./networkpolicies/simple-example/ \
227-
--target-pod-path ./examples/targets.json
228-
229-
pod in ns y with labels map[pod:a]:
230-
+---------+---------------+-----------------------------+---------------------+--------------------------+
231-
| TYPE | TARGET | SOURCE RULES | PEER | PORT/PROTOCOL |
232-
+---------+---------------+-----------------------------+---------------------+--------------------------+
233-
| Ingress | namespace: y | y/allow-label-to-label | no ips | no ports, no protocols |
234-
| | Match labels: | y/deny-all-for-label | | |
235-
| | pod: a | y/deny-all | | |
236-
+ + + +---------------------+--------------------------+
237-
| | | | namespace: y | all ports, all protocols |
238-
| | | | pods: Match labels: | |
239-
| | | | pod: c | |
240-
+---------+---------------+-----------------------------+---------------------+--------------------------+
241-
| | | | | |
242-
+---------+---------------+-----------------------------+---------------------+--------------------------+
243-
| Egress | namespace: y | y/deny-all-egress | all pods, all ips | all ports, all protocols |
244-
| | Match labels: | y/allow-all-egress-by-label | | |
245-
| | pod: a | | | |
246-
+---------+---------------+-----------------------------+---------------------+--------------------------+
247-
```
248-
249-
250-
#### Will policies allow or block traffic?
251-
252-
Given arbitrary traffic examples (from a source to a destination, including labels, over a port and protocol),
253-
this command parses network policies and determines if the traffic is allowed or not.
254-
255-
```
256-
cyclonus analyze \
257-
--mode query-traffic \
258-
--policy-path ./networkpolicies/simple-example/ \
259-
--traffic-path ./examples/traffic.json
260-
261-
Traffic:
262-
+--------------------------+-------------+---------------+-----------+-----------+------------+
263-
| PORT/PROTOCOL | SOURCE/DEST | POD IP | NAMESPACE | NS LABELS | POD LABELS |
264-
+--------------------------+-------------+---------------+-----------+-----------+------------+
265-
| 80 (serve-80-tcp) on TCP | source | 192.168.1.99 | y | ns: y | app: c |
266-
+ +-------------+---------------+ + +------------+
267-
| | destination | 192.168.1.100 | | | pod: b |
268-
+--------------------------+-------------+---------------+-----------+-----------+------------+
269-
270-
Is traffic allowed?
271-
+-------------+--------+---------------+
272-
| TYPE | ACTION | TARGET |
273-
+-------------+--------+---------------+
274-
| Ingress | Allow | namespace: y |
275-
| | | Match labels: |
276-
| | | pod: b |
277-
+ +--------+---------------+
278-
| | Deny | namespace: y |
279-
| | | all pods |
280-
+-------------+--------+---------------+
281-
| | | |
282-
+-------------+--------+---------------+
283-
| Egress | Deny | namespace: y |
284-
| | | all pods |
285-
+-------------+--------+---------------+
286-
| IS ALLOWED? | FALSE |
287-
+-------------+--------+---------------+
288-
```
289-
290-
#### Simulated probe
111+
- [run a single network policy test on a cluster](./docs/probe.md)
112+
- [run network policy conformance tests on a cluster](./docs/generator.md)
113+
- [analyze network policies](./docs/analyze.md).
291114

292-
Runs a simulated connectivity probe against a set of network policies, without using a kubernetes cluster.
293-
294-
```
295-
cyclonus analyze \
296-
--mode probe \
297-
--policy-path ./networkpolicies/simple-example/ \
298-
--probe-path ./examples/probe.json
299-
300-
Combined:
301-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
302-
| | X/A | X/B | X/C | Y/A | Y/B | Y/C | Z/A | Z/B | Z/C |
303-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
304-
| x/a | . | . | . | X | . | X | . | . | . |
305-
| x/b | . | . | . | X | . | X | . | . | . |
306-
| x/c | . | . | . | X | . | X | . | . | . |
307-
| y/a | . | . | . | X | . | X | . | . | . |
308-
| y/b | . | . | . | X | . | X | . | . | . |
309-
| y/c | X | X | X | X | X | X | X | X | X |
310-
| z/a | . | . | . | X | . | X | . | . | . |
311-
| z/b | . | . | . | X | . | X | . | . | . |
312-
| z/c | . | . | . | X | . | X | . | . | . |
313-
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
314-
```
315-
316-
#### Linter
317-
318-
Checks network policies for common problems.
319-
320-
```
321-
cyclonus analyze \
322-
--mode lint \
323-
--policy-path ./networkpolicies/simple-example
324-
325-
+-----------------+------------------------------+-------------------+-----------------------------+
326-
| SOURCE/RESOLVED | TYPE | TARGET | SOURCE POLICIES |
327-
+-----------------+------------------------------+-------------------+-----------------------------+
328-
| Resolved | CheckTargetAllEgressAllowed | namespace: y | y/allow-all-egress-by-label |
329-
| | | | |
330-
| | | pod selector: | |
331-
| | | matchExpressions: | |
332-
| | | - key: pod | |
333-
| | | operator: In | |
334-
| | | values: | |
335-
| | | - a | |
336-
| | | - b | |
337-
| | | | |
338-
+-----------------+------------------------------+-------------------+-----------------------------+
339-
| Resolved | CheckDNSBlockedOnTCP | namespace: y | y/deny-all-egress |
340-
| | | | |
341-
| | | pod selector: | |
342-
| | | {} | |
343-
| | | | |
344-
+-----------------+------------------------------+-------------------+-----------------------------+
345-
| Resolved | CheckDNSBlockedOnUDP | namespace: y | y/deny-all-egress |
346-
| | | | |
347-
| | | pod selector: | |
348-
| | | {} | |
349-
| | | | |
350-
+-----------------+------------------------------+-------------------+-----------------------------+
351-
```
352115

353116
## Sonobuoy plugin
354117

0 commit comments

Comments
 (0)