Skip to content

Commit e3c2364

Browse files
mattfenwickmattfenwick
committed
organize docs
1 parent 3a6fd79 commit e3c2364

File tree

3 files changed

+151
-153
lines changed

3 files changed

+151
-153
lines changed

‎README.md

+15-153
Original file line numberDiff line numberDiff line change
@@ -7,84 +7,15 @@ policies that suit your needs!
77

88
## Quickstart
99

10-
Grab the [latest release](https://github.com/mattfenwick/cyclonus/releases) to get started using Cyclonus.
10+
Users: check out our [Quickstart guide](./docs/quickstart.md)
11+
Developers: check out our [Developer guide](./docs/developer-guide.md)
1112

12-
### Run as a kubernetes job
1313

14-
Create a job.yaml file:
15-
```yaml
16-
apiVersion: batch/v1
17-
kind: Job
18-
metadata:
19-
name: cyclonus
20-
spec:
21-
template:
22-
spec:
23-
restartPolicy: Never
24-
containers:
25-
- command:
26-
- ./cyclonus
27-
- generate
28-
name: cyclonus
29-
imagePullPolicy: IfNotPresent
30-
image: mfenwick100/cyclonus:latest
31-
serviceAccount: cyclonus
32-
```
33-
34-
Then create a namespace, service account, and job:
35-
```bash
36-
kubectl create ns netpol
37-
kubectl create clusterrolebinding cyclonus --clusterrole=cluster-admin --serviceaccount=netpol:cyclonus
38-
kubectl create sa cyclonus -n netpol
39-
40-
kubectl create -f job.yaml -n netpol
41-
```
42-
43-
Use `kubectl logs -f` to watch your job go!
44-
45-
### Run on KinD
46-
47-
Take a look at the [kind directory](./hack/kind):
48-
49-
```
50-
ls hack/kind
51-
antrea calico cilium ovn-kubernetes run-cyclonus.sh
52-
```
53-
54-
Choose the right job for your CNI, then run:
55-
56-
```
57-
cd hack/kind
58-
CNI=calico RUN_FROM_SOURCE=false ./run-cyclonus.sh
59-
```
60-
61-
This will:
62-
63-
- create a namespace, service account, and cluster role binding for cyclonus
64-
- create a cyclonus job
65-
66-
Pull the logs from the job:
67-
68-
```
69-
kubectl logs -f -n netpol cyclonus-abcde
70-
```
71-
72-
### Run from source
73-
74-
Assuming you have a kube cluster and your kubectl is configured to point to it, you can run:
75-
76-
```
77-
cd cmd/cyclonus
78-
go run main.go generate
79-
```
80-
81-
### Docker images
82-
83-
Images are available at [mfenwick100/cyclonus](https://hub.docker.com/r/mfenwick100/cyclonus/tags?page=1&ordering=last_updated):
14+
## Cyclonus functionality
8415

85-
```
86-
docker pull docker.io/mfenwick100/cyclonus:latest
87-
```
16+
- [run a single network policy test on a cluster](./docs/probe.md)
17+
- [run network policy conformance tests on a cluster](./docs/generator.md)
18+
- [analyze network policies](./docs/analyze.md)
8819

8920

9021
## Integrations
@@ -95,91 +26,22 @@ Cyclonus is available as a [krew/kubectl plugin](https://github.com/mattfenwick/
9526

9627
- [Set up krew](https://krew.sigs.k8s.io/docs/user-guide/quickstart/)
9728
- install cyclonus through krew: `kubectl krew install cyclonus`
98-
- use cyclonus as a kubectl plugin: `kubectl cyclonus -h`.
99-
100-
### Antrea testing
101-
102-
[Cyclonus runs network policy tests for Antrea on a daily basis](https://github.com/vmware-tanzu/antrea/actions/workflows/netpol_cyclonus.yml).
103-
104-
### Cilium testing
105-
106-
[Cyclonus runs network policy tests for Cilium on a daily basis](https://github.com/cilium/cilium/pull/14889).
107-
108-
109-
## Cyclonus functionality
110-
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).
114-
115-
116-
## Sonobuoy plugin
117-
118-
Check out [our sonobuoy plugin](./hack/sonobuoy)!
119-
120-
## Developer guide
121-
122-
### Setup
123-
124-
- [Get set up with golang 1.16](https://golang.org/dl/)
125-
- clone this repo
126-
127-
git clone [email protected]:mattfenwick/cyclonus.git
128-
cd cyclonus
129-
130-
- set up a KinD cluster with a CNI that supports network policies
131-
132-
pushd kind/calico
133-
./setup.sh
134-
popd
135-
136-
- run cyclonus
137-
138-
go run cmd/cyclonus/main.go generate --mode=example
139-
140-
- run format, vet, tests
141-
142-
make fmt
143-
make vet
144-
make test
145-
146-
## How to Release Binaries
147-
148-
See `goreleaser`'s requirements [here](https://goreleaser.com/environment/).
149-
150-
Get a [GitHub Personal Access Token](https://github.com/settings/tokens/new) and add the `repo` scope.
151-
Set `GITHUB_TOKEN` to this value:
152-
153-
```bash
154-
export GITHUB_TOKEN=...
155-
```
156-
157-
[See here for more information on github tokens](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
158-
159-
Choose a tag/release name, create and push a tag:
160-
161-
```bash
162-
TAG=v0.0.1
163-
164-
git tag $TAG
165-
git push origin $TAG
166-
```
29+
- use cyclonus as a kubectl plugin: `kubectl cyclonus -h`
16730

168-
Cut a release:
31+
Antrea testing: [Cyclonus runs network policy tests for Antrea on a daily basis](https://github.com/vmware-tanzu/antrea/actions/workflows/netpol_cyclonus.yml).
16932

170-
```bash
171-
goreleaser release --rm-dist
172-
```
33+
Cilium testing: [Cyclonus runs network policy tests for Cilium on a daily basis](https://github.com/cilium/cilium/pull/14889).
17334

174-
Make a test release:
35+
Sonobuoy plugin: [run Cyclonus tests through Sonobuoy](./hack/sonobuoy)!
17536

176-
```bash
177-
goreleaser release --snapshot --rm-dist
178-
```
17937

18038
## Motivation and History
18139

182-
Testing network policies for CNI providers on Kubernetes has historically been very difficult, requiring a lot of boiler plate. This was recently improved upstream via truth table based tests ([see KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/1611-network-policy-validation)). Cyclonus is the next evolution of the truth table tests which are part of upstream Kubernetes. Cyclonus generates hundreds of network policies, their connectivity tables, and outputs results in the same, easy to read format.
40+
Testing network policies for CNI providers on Kubernetes has historically been very difficult, requiring a lot of boiler plate.
41+
This was recently improved upstream via truth table based tests
42+
([see KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/1611-network-policy-validation)).
43+
Cyclonus is the next evolution of the truth table tests which are part of upstream Kubernetes.
44+
Cyclonus generates hundreds of network policies, their connectivity tables, and outputs results in the same, easy to read format.
18345

18446
## Thanks to contributors
18547

‎docs/developer-guide.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Developer guide
2+
3+
## Setup
4+
5+
- [Get set up with golang 1.16](https://golang.org/dl/)
6+
- clone this repo
7+
8+
git clone [email protected]:mattfenwick/cyclonus.git
9+
cd cyclonus
10+
11+
- set up a KinD cluster with a CNI that supports network policies
12+
13+
pushd hack/kind/calico
14+
./setup.sh
15+
popd
16+
17+
- run cyclonus
18+
19+
go run cmd/cyclonus/main.go generate --mock --perturbation-wait-seconds 0
20+
21+
- run format, vet, tests
22+
23+
make fmt
24+
make vet
25+
make test
26+
27+
## How to Release Binaries
28+
29+
See `goreleaser`'s requirements [here](https://goreleaser.com/environment/).
30+
31+
Get a [GitHub Personal Access Token](https://github.com/settings/tokens/new) and add the `repo` scope.
32+
Set `GITHUB_TOKEN` to this value:
33+
34+
```bash
35+
export GITHUB_TOKEN=...
36+
```
37+
38+
[See here for more information on github tokens](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
39+
40+
Choose a tag/release name, create and push a tag:
41+
42+
```bash
43+
TAG=v0.0.1
44+
45+
git tag $TAG
46+
git push origin $TAG
47+
```
48+
49+
Cut a release:
50+
51+
```bash
52+
goreleaser release --rm-dist
53+
```
54+
55+
Make a test release:
56+
57+
```bash
58+
goreleaser release --snapshot --rm-dist
59+
```

‎docs/quickstart.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Quickstart guide
2+
3+
Grab the [latest release](https://github.com/mattfenwick/cyclonus/releases) to get started using Cyclonus.
4+
5+
Images are available at [mfenwick100/cyclonus](https://hub.docker.com/r/mfenwick100/cyclonus/tags?page=1&ordering=last_updated):
6+
7+
```
8+
docker pull docker.io/mfenwick100/cyclonus:latest
9+
```
10+
11+
## Run as a kubernetes job
12+
13+
Create a job.yaml file:
14+
```yaml
15+
apiVersion: batch/v1
16+
kind: Job
17+
metadata:
18+
name: cyclonus
19+
spec:
20+
template:
21+
spec:
22+
restartPolicy: Never
23+
containers:
24+
- command:
25+
- ./cyclonus
26+
- generate
27+
name: cyclonus
28+
imagePullPolicy: IfNotPresent
29+
image: mfenwick100/cyclonus:latest
30+
serviceAccount: cyclonus
31+
```
32+
33+
Then create a namespace, service account, and job:
34+
```bash
35+
kubectl create ns netpol
36+
kubectl create clusterrolebinding cyclonus --clusterrole=cluster-admin --serviceaccount=netpol:cyclonus
37+
kubectl create sa cyclonus -n netpol
38+
39+
kubectl create -f job.yaml -n netpol
40+
```
41+
42+
Use `kubectl logs -f` to watch your job go!
43+
44+
## Run on KinD
45+
46+
Take a look at the [kind directory](./hack/kind):
47+
48+
```
49+
ls hack/kind
50+
antrea calico cilium ovn-kubernetes run-cyclonus.sh
51+
```
52+
53+
Choose the right job for your CNI, then run:
54+
55+
```
56+
cd hack/kind
57+
CNI=calico RUN_FROM_SOURCE=false ./run-cyclonus.sh
58+
```
59+
60+
This will:
61+
62+
- create a namespace, service account, and cluster role binding for cyclonus
63+
- create a cyclonus job
64+
65+
Pull the logs from the job:
66+
67+
```
68+
kubectl logs -f -n netpol cyclonus-abcde
69+
```
70+
71+
## Run from source
72+
73+
Assuming you have a kube cluster and your kubectl is configured to point to it, you can run:
74+
75+
```
76+
go run cmd/cyclonus/main.go generate
77+
```

0 commit comments

Comments
 (0)