generated from kubernetes/kubernetes-template-project
-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #245 from huntergregory/walkthrough
feat: [Policy Assistant] walkthrough mode and a README (KubeCon demo PR 2/2)
- Loading branch information
Showing
17 changed files
with
631 additions
and
123 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,213 @@ | ||
| # 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 all APIs for network policies. | ||
| Currently, the APIs are: | ||
|
|
||
| More details here: [Cyclonus](https://github.com/mattfenwick/cyclonus). | ||
| - [NetworkPolicy (v1)](https://kubernetes.io/docs/concepts/services-networking/network-policies/) | ||
| - [AdminNetworkPolicy and BaselineAdminNetworkPolicy](https://network-policy-api.sigs.k8s.io/api-overview/) | ||
|
|
||
| ## Usage | ||
| ## Overview | ||
|
|
||
| CLI currently under development. Will build off of `cyclonus analyze` (visualization) and `cyclonus generate` (conformance tests). | ||
| 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. | ||
|
|
||
| Policy Assistant is a static analysis tool which ***simulates the action of network policies*** for the given traffic. Policy Assistant can read resources either from your cluster or from config files, so no cluster is needed. | ||
|
|
||
| For instance, Policy Assistant can simulate and walk through which policies impact cluster traffic: | ||
|
|
||
| ```shell | ||
| $ pola analyze --namespace demo --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) | | | ||
| +---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ | ||
| ``` | ||
|
|
||
| ### Quick Install | ||
|
|
||
| Download the latest `pola` release either from GitHub ([web page](https://github.com/kubernetes-sigs/network-policy-api/releases/v0.0.1-pola)) or via these bash commands: | ||
|
|
||
| ```bash | ||
| curl -O https://github.com/kubernetes-sigs/network-policy-api/releases/download/v0.0.1-pola/pola_linux_amd64.tar.gz | ||
| # optionally verify check sum | ||
| tar -xvf pola_linux_amd64.tar.gz | ||
| ./pola --help | ||
| ``` | ||
|
|
||
| Alternatively, [install from source](#make-from-source). | ||
|
|
||
| See [example usage](#example-usage) below. | ||
|
|
||
| ### Fuzz Testing Capability | ||
|
|
||
| CNI developers may benefit from Policy Assistant as well. | ||
| Policy Assistant is capable of providing a fuzz testing framework (see [#154](https://github.com/kubernetes-sigs/network-policy-api/issues/154)) which CNI developers could run as a second conformance profile (to ensure the CNI's implementation is compliant with API specifications). | ||
|
|
||
| ### Roadmap | ||
|
|
||
| Planning is currently via GitHub issues. | ||
|
|
||
| - Original issue for Policy Assistant: [#150](https://github.com/kubernetes-sigs/network-policy-api/issues/150). | ||
| - First CLI release: [#255](https://github.com/kubernetes-sigs/network-policy-api/issues/255) | ||
|
|
||
| ### 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). | ||
|
|
||
| ## Example Usage | ||
|
|
||
| ### Analyze | ||
|
|
||
| > [!NOTE] | ||
| > The CLI binary is still called "cyclonus". This will soon be renamed per [#254](https://github.com/kubernetes-sigs/network-policy-api/issues/254). | ||
| #### "explain" mode | ||
|
|
||
| Visualize all your policies in a table. | ||
|
|
||
| ```shell | ||
| $ pola analyze --mode explain --policy-path cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/ | ||
| 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 is more intuitive and informative than "probe" mode. | ||
| Visualize how traffic would be allowed/denied. | ||
|
|
||
| ```shell | ||
| $ pola analyze --mode probe --probe-path examples/demos/kubecon-eu-2024/demo-probe.json --policy-path cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/ | ||
| 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 | ||
| $ pola analyze --mode walkthrough --policy-path cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/ | ||
| 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: | ||
| ### Make from Source | ||
|
|
||
| > [!NOTE] | ||
| > The CLI binary is still called "cyclonus". This will soon be renamed per [#254](https://github.com/kubernetes-sigs/network-policy-api/issues/254). | ||
| 1. Clone the repo. | ||
| 2. `cd cmd/policy-assistant` | ||
| 3. `make cyclonus` | ||
| 4. The `cyclonus` binary will be produced at *cmd/cyclonus/cyclonus*. | ||
|
|
||
| ### 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. | ||
|
|
||
| #### GitHub Action | ||
|
|
||
| PRs must pass the GitHub Action for Policy Assistant specified under *.github/*. |
33 changes: 33 additions & 0 deletions
33
cmd/policy-assistant/examples/demos/kubecon-eu-2024/demo-probe.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"}] | ||
| } | ||
| ] | ||
| } | ||
| } |
20 changes: 20 additions & 0 deletions
20
cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/anp1.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
20 changes: 20 additions & 0 deletions
20
cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/anp2.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
20 changes: 20 additions & 0 deletions
20
cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/anp3.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
15 changes: 15 additions & 0 deletions
15
cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/banp.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: {} |
12 changes: 12 additions & 0 deletions
12
cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/npv1.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: [] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.