diff --git a/cmd/policy-assistant/examples/demos/walkthrough/README.md b/cmd/policy-assistant/examples/demos/walkthrough/README.md index 85c95a86..645ae520 100644 --- a/cmd/policy-assistant/examples/demos/walkthrough/README.md +++ b/cmd/policy-assistant/examples/demos/walkthrough/README.md @@ -1,12 +1,15 @@ ## Use Cases 1. Test a new policy before applying it to your cluster. -2. Understand which policies are affecting traffic in your cluster. +1. Understand which policies are affecting traffic in your cluster. +1. Without a cluster, understand how policies would affect traffic for "fake" Pods. ## Overview ### Walkthrough +How do policies impact traffic? + ```bash # single source/destination read from cluster. policies read from YAML files policy-assistant analyze --mode walkthrough \ @@ -38,10 +41,10 @@ Example output: ### Explain -We can also summarize our policies in a table: +You can also summarize your policies in a table: ```bash -$ policy-assistant analyze --mode walkthrough --policy-path policies/ +$ policy-assistant analyze --mode explain --policy-path policies/ explained policies: +---------+------------+------------------------------------+-----------------------+---------------------------------+--------------------------+ | TYPE | SUBJECT | SOURCE RULES | PEER | ACTION | PORT/PROTOCOL | @@ -73,43 +76,189 @@ explained policies: To try for yourself: 1. Download `policy-assistant` via the [Quick Install](../../../README.md#quick-install) guide. -1. Leverage the JSON/YAML files in this folder. -1. Not required: create a Kubernetes cluster and apply any desired YAML files. +1. This document references files from this folder. Feel free to clone the repo and change into this directory. -## Walkthrough Usage +### Demo 1: Without a Cluster -### Specifying Policies +You can also use `policy-assistant` with a cluster. See [Demo 2](#demo-2-using-a-cluster) for more info. -#### Option 1: reference policies from YAML files +#### Specify Policies from File -Use this argument: `--policy-path ` +Specify your policy YAML(s) with `--policy-path`. -#### Option 2: reference policies from cluster +`--mode explain` will explain the policy files: -Specify the `--namespace` or `--all-namespaces`. +```bash +$ policy-assistant analyze --mode explain --policy-path policies/ +explained policies: ++---------+------------+------------------------------------+-----------------------+---------------------------------+--------------------------+ +| TYPE | SUBJECT | SOURCE RULES | PEER | ACTION | PORT/PROTOCOL | ++---------+------------+------------------------------------+-----------------------+---------------------------------+--------------------------+ +| Ingress | Namespace: | [NPv1] demo/deny-anything-to-pod-a | no peers | NPv1: | none | +| | demo | | | Allow any peers | | +| | Pod: | | | | | +| | pod = a | | | | | ++ +------------+------------------------------------+-----------------------+---------------------------------+--------------------------+ +| | Namespace: | [ANP] default/anp1 | Namespace: | BANP: | all ports, all protocols | +| | all | [ANP] default/anp2 | all | Deny | | +| | | [BANP] default/default | Pod: | | | +| | | | all | | | ++ + + +-----------------------+---------------------------------+ + +| | | | Namespace: | ANP: | | +| | | | development = true | pri=2 (development-ns): Pass | | +| | | | Pod: | | | +| | | | all | | | ++ + + +-----------------------+---------------------------------+--------------------------+ +| | | | Namespace: | ANP: | port 80 on protocol TCP | +| | | | all | pri=1 (allow-80): Allow | | +| | | | Pod: | | | +| | | | all | | | ++---------+------------+------------------------------------+-----------------------+---------------------------------+--------------------------+ +``` + +#### Walk through Traffic ("Fake" Pods) -### Specifying Pods +Now let's walk through how these policies impact traffic. -#### Option 1: specify single source/destination in CLI args +Specify your traffic in JSON like in *traffic-no-cluster.json*. -You can use the following arguments to reference Pods from cluster by workload name: +Then use `--mode walkthrough` with an extra argument for `--traffic-path`: ```bash -policy-assistant analyze --mode walkthrough \ +$ policy-assistant analyze --mode walkthrough --policy-path policies/ --traffic-path traffic-no-cluster.json +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] No-Op -> [BANP] Deny (baseline-deny) | | ++--------------------------------------------+ +-----------------------------------------------------------------------------+ + +| demo2/[app=nginx] -> demo/[pod=a]:81 (TCP) | | [ANP] Pass (development-ns) -> [NPv1] Dropped (demo/deny-anything-to-pod-a) | | ++--------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +``` + +### Demo 2: Using a Cluster + +Create the demo namespace: + +```bash +kubectl create ns demo +``` + +Create deployment `a` and pod `b`: + +```bash +kubectl apply -f demo-deployment-a.yaml +kubectl apply -f demo-pod-b.yaml +``` + +Create the policies (you can also keep referencing policies via `--policy-path` if you'd like): + +```bash +# install the v0.1.1 version of AdminNetworkPolicy and BaselineAdminNetworkPolicy +wget https://github.com/kubernetes-sigs/network-policy-api/releases/download/v0.1.1/install.yaml +kubectl apply -f install.yaml + +# apply policies +kubectl apply -f policies/ +``` + +#### Specifying Policies from Cluster + +You can still [specify policies from file](#specify-policies-from-file) if you'd like. + +To specify policies from cluster, use `--namespace` or `--all-namespaces`. + +Any AdminNetworkPolicy and BaselineAdminNetworkPolicy from the cluster will always be included since they are cluster-scoped objects. + +Here's an example of `--explain mode` with `--namespace x` to get any NetworkPolicy from the `x` namespace (this namespace is not part of the demo resources actually): + +```bash +$ policy-assistant analyze --mode explain -n x +explained policies: ++---------+------------+------------------------+-----------------------+---------------------------------+--------------------------+ +| TYPE | SUBJECT | SOURCE RULES | PEER | ACTION | PORT/PROTOCOL | ++---------+------------+------------------------+-----------------------+---------------------------------+--------------------------+ +| Ingress | Namespace: | [NPv1] x/base | Namespace: | NPv1: | port 80 on protocol TCP | +| | x | | ns In [x y] | Allow any peers | | +| | Pod: | | Pod: | | | +| | pod = a | | pod In [b c] | | | ++ +------------+------------------------+-----------------------+---------------------------------+--------------------------+ +| | Namespace: | [ANP] default/anp1 | Namespace: | BANP: | all ports, all protocols | +| | all | [ANP] default/anp2 | all | Deny | | +| | | [BANP] default/default | Pod: | | | +| | | | all | | | ++ + + +-----------------------+---------------------------------+ + +| | | | Namespace: | ANP: | | +| | | | development = true | pri=2 (development-ns): Pass | | +| | | | Pod: | | | +| | | | all | | | ++ + + +-----------------------+---------------------------------+--------------------------+ +| | | | Namespace: | ANP: | port 80 on protocol TCP | +| | | | all | pri=1 (allow-80): Allow | | +| | | | Pod: | | | +| | | | all | | | ++---------+------------+------------------------+-----------------------+---------------------------------+--------------------------+ +| | | | | | | ++---------+------------+------------------------+-----------------------+---------------------------------+--------------------------+ +| Egress | Namespace: | [NPv1] x/base | 10.224.1.0/24 | NPv1: | port 80 on protocol TCP | +| | x | | except [] | Allow any peers | | +| | Pod: | | | | | +| | pod = a | | | | | ++ + + +-----------------------+ +--------------------------+ +| | | | all pods, all ips | | port 53 on protocol UDP | +| | | | | | port 53 on protocol TCP | +| | | | | | | +| | | | | | | ++---------+------------+------------------------+-----------------------+---------------------------------+--------------------------+ +``` + +#### Walk Through Traffic (Cluster Pods) + +Reference Pods from cluster by workload name such as `demo/deployment/a` or `kube-system/daemonset/kube-proxy` etc. + +You can still [specify traffic for "fake" Pods](#walk-through-traffic-fake-pods) if you'd like. + +#### Option 1: single source/destination in CLI args + +You can specify workloads, port, and protocol via the CLI: + +```bash +$ policy-assistant analyze --mode walkthrough --all-namespaces \ --src-workload demo/deployment/a \ --dst-workload demo/pod/b \ --port 81 \ --protocol TCP +verdict walkthrough: ++------------------------------------------+---------+--------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++------------------------------------------+---------+--------------------------------------------+------------------------------+ +| demo/deployment/a -> demo/pod/b:81 (TCP) | Denied | [ANP] No-Op -> [BANP] Deny (baseline-deny) | no policies targeting egress | ++------------------------------------------+---------+--------------------------------------------+------------------------------+ ``` -#### Option 2: specify multiple source/destination pairs in JSON +This example uses policies from cluster, but you could also [specify policies from file](#specify-policies-from-file). + +#### Option 2: multiple source/destination pairs in JSON -You can also reference Pods via JSON. -You can also specify Pods which are not running in a cluster in this JSON. +Specify source/destination workload names in your traffic like in *traffic.json*. -See the example *traffic.json* file. +Notice how you can still specify "fake" sources/destinations like above. + +*traffic.json* has an example of mix and matching a "fake" source (nginx) and a destination workload from the cluster. ```bash -policy-assistant analyze --mode walkthrough \ - --traffic-path traffic.json +verdict walkthrough: ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| demo/deployment/a -> demo/pod/b:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+ + +| demo/deployment/a -> demo/pod/b:81 (TCP) | Denied | [ANP] No-Op -> [BANP] Deny (baseline-deny) | | ++-------------------------------------------------+ +-----------------------------------------------------------------------------+ + +| demo2/[app=nginx] -> demo/deployment/a:81 (TCP) | | [ANP] Pass (development-ns) -> [NPv1] Dropped (demo/deny-anything-to-pod-a) | | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ ``` + +Again, this example uses policies from cluster, but you could also [specify policies from file](#specify-policies-from-file).