From 9db719beb3e31ce247dd284cad8ab3a1016cfef1 Mon Sep 17 00:00:00 2001 From: Hunter Gregory <42728408+huntergregory@users.noreply.github.com> Date: Wed, 7 Aug 2024 17:00:15 -0700 Subject: [PATCH] docs: README updates and kubecon demo yamls Signed-off-by: Hunter Gregory <42728408+huntergregory@users.noreply.github.com> --- cmd/policy-assistant/README.md | 170 +++++++++++++++++- .../demos/kubecon-eu-2024/anp/anp1.yaml | 20 +++ .../demos/kubecon-eu-2024/anp/anp2.yaml | 20 +++ .../demos/kubecon-eu-2024/anp/anp3.yaml | 20 +++ .../demos/kubecon-eu-2024/banp/banp.yaml | 15 ++ .../demos/kubecon-eu-2024/demo-probe.json | 33 ++++ .../demos/kubecon-eu-2024/npv1/npv1.yaml | 12 ++ 7 files changed, 285 insertions(+), 5 deletions(-) create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp1.yaml create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp2.yaml create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp3.yaml create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/banp/banp.yaml create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/demo-probe.json create mode 100644 cmd/policy-assistant/examples/demos/kubecon-eu-2024/npv1/npv1.yaml diff --git a/cmd/policy-assistant/README.md b/cmd/policy-assistant/README.md index 2479bc46..c88e4c15 100644 --- a/cmd/policy-assistant/README.md +++ b/cmd/policy-assistant/README.md @@ -1,16 +1,176 @@ # Policy Assistant (derived from Cyclonus) -Explains your configuration of (Baseline)AdminNetworkPolicy and v1 NetworkPolicy. Additionally, can test conformance of (B)ANP and v1 NetworkPolicy via a connectivity matrix. Derived from the great work of @mattfenwick et al. in [Cyclonus](https://github.com/mattfenwick/cyclonus). +Policy Assistant is a project to assist users regarding the three APIs for network policies (NetworkPolicy, AdminNetworkPolicy, BaselineAdminNetworkPolicy). -More details here: [Cyclonus](https://github.com/mattfenwick/cyclonus). +## Overview -## Usage +Policy Assistant is a CLI (command-line interface) designed to help users: +1. ***Develop/understand policy configurations***. +1. ***Prevent pitfalls*** while developing policies. +1. ***Troubleshoot*** network policy issues. -CLI currently under development. Will build off of `cyclonus analyze` (visualization) and `cyclonus generate` (conformance tests). +Policy Assistant is a static analysis tool which ***simulates the action of network policies*** for the given traffic. ***No cluster is needed.*** Policy Assistant can read resources either from your cluster or from config files. + +CNI developers may benefit from Policy Assistant as well. +Policy Assistant is capable of providing a fuzz testing framework which CNI developers could run as a second conformance profile (to ensure the CNI's implementation is compliant with API specifications). + +### Roadmap + +We are maintaining the project via GitHub issues. +Parent issue: [#150](https://github.com/kubernetes-sigs/network-policy-api/issues/150). + +### KubeCon EU 2024 + +For a presentation and discussion on Policy Assistant and the admin policy APIs, see [this talk](https://youtu.be/riSv0g-TNtI?si=jiRy2mAKB0OVMFJF&t=1232). + +## Installation + +### Option 1: Download from Releases + +*Work in progress.* + +### Option 2: Make from Source + +> [!NOTE] +> The CLI binary is still called "cyclonus". This will soon be renamed. + +1. Clone the repo. +2. `cd cmd/policy-assistant` +3. `make cyclonus` +4. The `cyclonus` binary will be produced at *cmd/cyclonus/cyclonus*. + +## Example Usage + +### Analyze + +> [!NOTE] +> The CLI binary is still called "cyclonus". This will soon be renamed. + +#### "explain" mode + +Visualize all your policies in a table. + +```shell +$ ./cyclonus analyze --policy-path examples/demos/kubecon-eu-2024 --mode explain +explained policies: ++---------+---------------------------------------+---------------------------+------------+----------------------------+--------------------------+ +| TYPE | SUBJECT | SOURCE RULES | PEER | ACTION | PORT/PROTOCOL | ++---------+---------------------------------------+---------------------------+------------+----------------------------+--------------------------+ +| Ingress | Namespace: | [NPv1] demo/deny-to-pod-a | no peers | NPv1: | none | +| | demo | | | Allow any peers | | +| | Pod: | | | | | +| | pod = a | | | | | ++ +---------------------------------------+---------------------------+------------+----------------------------+--------------------------+ +| | Namespace: | [ANP] default/anp1 | Namespace: | BANP: | all ports, all protocols | +| | kubernetes.io/metadata.name = demo | [ANP] default/anp2 | all | Deny | | +| | | [ANP] default/anp3 | Pod: | | | +| | | [BANP] default/default | all | | | ++ + + + +----------------------------+--------------------------+ +| | | | | ANP: | port 80 on protocol TCP | +| | | | | pri=1 (allow-80): Allow | | +| | | | | | | +| | | | | | | ++ + + + +----------------------------+--------------------------+ +| | | | | ANP: | port 81 on protocol TCP | +| | | | | pri=2 (pass-81): Pass | | +| | | | | pri=3 (deny-81): Deny | | +| | | | | | | ++---------+---------------------------------------+---------------------------+------------+----------------------------+--------------------------+ +``` + +#### "probe" mode + +> [!NOTE] +> "walkthrough" mode displays more granular info in a more intuitive way. + +Visualize how traffic would be allowed/denied. + +```shell +$ ./cyclonus analyze --policy-path examples/demos/kubecon-eu-2024 --mode probe --probe-path examples/demos/kubecon-eu-2024/demo-probe.json +probe (simulated connectivity): +INFO[2024-08-07T17:26:28-07:00] probe on port 80, protocol TCP +Ingress: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | X | # | ++--------+--------+--------+ + +Egress: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | . | # | ++--------+--------+--------+ + +Combined: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | X | # | ++--------+--------+--------+ + + + +INFO[2024-08-07T17:26:28-07:00] probe on port 81, protocol TCP +Ingress: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | X | # | ++--------+--------+--------+ + +Egress: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | . | # | ++--------+--------+--------+ + +Combined: ++--------+--------+--------+ +| | DEMO/A | DEMO/B | ++--------+--------+--------+ +| demo/a | # | . | +| demo/b | X | # | ++--------+--------+--------+ +``` + +#### "walkthrough" mode + +Visualize how traffic would be allowed/denied and which policies are causing the verdict. + +```shell +$ ./cyclonus analyze --policy-path examples/demos/kubecon-eu-2024 --mode walkthrough +verdict walkthrough: ++---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ +| demo/[pod=a] -> demo/[pod=b]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | ++---------------------------------------+---------+-------------------------------------------------------------+ + +| demo/[pod=a] -> demo/[pod=b]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [BANP] Deny (baseline-deny) | | ++---------------------------------------+---------+-------------------------------------------------------------+ + +| demo/[pod=b] -> demo/[pod=a]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | | ++---------------------------------------+---------+-------------------------------------------------------------+ + +| demo/[pod=b] -> demo/[pod=a]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [NPv1] Dropped (demo/deny-to-pod-a) | | ++---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ +``` ## Development -Integration tests located at *test/integration/integration_test.go*. The tests verify: +See [Make from Source](#option-2-make-from-source). + +### Testing + +Run `go test ./...` in the *cmd/policy-assistant/* directory. + +Integration tests located at *test/integration/integration_test.go*. +The tests verify: 1. Building/translating Policy specs into interim data structures (matchers). 2. Simulation of expected connectivity for ANP, BANP, and v1 NetPols. diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp1.yaml b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp1.yaml new file mode 100644 index 00000000..c81b4dbf --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp1.yaml @@ -0,0 +1,20 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: AdminNetworkPolicy +metadata: + name: anp1 +spec: + priority: 1 + subject: + namespaces: + matchLabels: + kubernetes.io/metadata.name: demo + ingress: + - name: "allow-80" + action: "Allow" + from: + - namespaces: + namespaceSelector: {} + ports: + - portNumber: + protocol: TCP + port: 80 diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp2.yaml b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp2.yaml new file mode 100644 index 00000000..6501a219 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp2.yaml @@ -0,0 +1,20 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: AdminNetworkPolicy +metadata: + name: anp2 +spec: + priority: 2 + subject: + namespaces: + matchLabels: + kubernetes.io/metadata.name: demo + ingress: + - name: "pass-81" + action: "Pass" + from: + - namespaces: + namespaceSelector: {} + ports: + - portNumber: + protocol: TCP + port: 81 diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp3.yaml b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp3.yaml new file mode 100644 index 00000000..e9c36dfa --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/anp/anp3.yaml @@ -0,0 +1,20 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: AdminNetworkPolicy +metadata: + name: anp3 +spec: + priority: 3 + subject: + namespaces: + matchLabels: + kubernetes.io/metadata.name: demo + ingress: + - name: "deny-81" + action: "Deny" + from: + - namespaces: + namespaceSelector: {} + ports: + - portNumber: + protocol: TCP + port: 81 diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/banp/banp.yaml b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/banp/banp.yaml new file mode 100644 index 00000000..24e0cf06 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/banp/banp.yaml @@ -0,0 +1,15 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: BaselineAdminNetworkPolicy +metadata: + name: default +spec: + subject: + namespaces: + matchLabels: + kubernetes.io/metadata.name: demo + ingress: + - name: "baseline-deny" + action: "Deny" + from: + - namespaces: + namespaceSelector: {} diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/demo-probe.json b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/demo-probe.json new file mode 100644 index 00000000..621e6485 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/demo-probe.json @@ -0,0 +1,33 @@ +{ + "Probes": [ + { + "Protocol": "TCP", + "Port": 80 + }, + { + "Protocol": "TCP", + "Port": 81 + } + ], + "Resources": { + "Namespaces": { + "demo": {"ns": "demo"} + }, + "Pods": [ + { + "Namespace": "demo", + "Name": "a", + "Labels": {"pod": "a"}, + "IP": "192.168.1.8", + "Containers": [{"Name": "cont-1", "Port": 80, "PortName": "serve-80-tcp","Protocol": "tcp"}, {"Name": "cont-2", "Port": 81, "PortName": "serve-81-tcp","Protocol": "tcp"}] + }, + { + "Namespace": "demo", + "Name": "b", + "Labels": {"pod": "b"}, + "IP": "192.168.1.9", + "Containers": [{"Name": "cont-1", "Port": 80, "PortName": "serve-80-tcp","Protocol": "tcp"}, {"Name": "cont-2", "Port": 81, "PortName": "serve-81-tcp","Protocol": "tcp"}] + } + ] + } +} diff --git a/cmd/policy-assistant/examples/demos/kubecon-eu-2024/npv1/npv1.yaml b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/npv1/npv1.yaml new file mode 100644 index 00000000..b5577419 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/kubecon-eu-2024/npv1/npv1.yaml @@ -0,0 +1,12 @@ +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: deny-to-pod-a + namespace: demo +spec: + policyTypes: + - Ingress + podSelector: + matchLabels: + pod: a + ingress: []