Skip to content

Commit d0c39aa

Browse files
gaurav-nelsongaurav-nelson
committed
Added docs for explanations
1 parent 4fe7c6a commit d0c39aa

6 files changed

+112
-1
lines changed

‎modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,7 @@ Each line is composed of the following elements:
4949
* `conn`:: Represents the permissible connectivity attributes.
5050
5151
An endpoint follows the format `namespace/name[Kind]`. For example, `default/backend[Deployment]`.
52+
53+
Opional: To see which policies and rules are responsible for allowing or denying specific connections, you can use the `--explain` option with the `roxctl netpol connectivity map` command.
54+
You can use the output to debug network policy configurations.
55+
For more information about understanding the explanation output, see "Retriving explanations".

‎modules/retrieving-explanations.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operating/build-time-network-policy-tools.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="retrieving-explanations_{context}"]
7+
= Retrieving explanations
8+
9+
[role="_abstract"]
10+
You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations.
11+
12+
.Procedure
13+
14+
* To generate a connectivity report with explanations, run the following command:
15+
+
16+
[source,terminal,subs="+quotes"]
17+
----
18+
$ roxctl netpol connectivity map --explain <folder_path> <1>
19+
----
20+
+
21+
<1> Specify the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis.
22+
23+
When you use the `--explain` flag, the connectivity report includes an *explanation section* that details the specific policies and rules relevant to each allowed or blocked connection.

‎modules/roxctl-netpol-connectivity-map-command-options.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ The `roxctl netpol connectivity map` command supports the following options:
1313

1414
|Option |Description
1515

16+
|`--explain`
17+
|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format.
18+
1619
|`--fail`
1720
|Fail on the first encountered error. The default value is `false`.
1821

‎modules/roxctl-netpol-connectivity-map.adoc‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ $ roxctl netpol connectivity map <folder_path> [flags] <1>
2121
|===
2222
|Option |Description
2323

24-
|`--exposure`
24+
|`--explain`
25+
|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format.
26+
27+
|`--exposure`
2528
|Enhance the analysis of permitted connectivity by using exposure analysis. The default value is `false`.
2629

2730
|`--fail`
@@ -33,6 +36,9 @@ $ roxctl netpol connectivity map <folder_path> [flags] <1>
3336
|`-f`, `--output-file string`
3437
|Save the connections list output into a specific file.
3538

39+
|`-h`, `--help`
40+
|View the help text for the `roxctl netpol connectivity map` command.
41+
3642
|`-o`, `--output-format string`
3743
|Configure the connections list in a specific format. Supported formats include `txt`, `json`, `md`, `dot`, and `csv`. The default value is `txt`.
3844

‎modules/understanding-connectivity-explanations.adoc‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operating/build-time-network-policy-tools.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="understanding-connectivity-explanations_{context}"]
7+
= Understanding Connectivity Explanations
8+
9+
[role="_abstract"]
10+
To understand precisely which parts of your Kubernetes network policy YAML files are responsible for allowing or denying connections, you can use the `roxctl netpol connectivity map` command which includes an explainability mode.
11+
You can debug and refine your network policies by using the explainability mode which provides additional details beyond the standard connectivity report.
12+
13+
As a developer or DevOps professional, you might encounter situations where a connection you expect to be open is denied, or you need to confirm which specific rules permit a connection. For example, some common issues are:
14+
15+
* Mismatched ingress and egress rules, where one side of a connection allows traffic but the other denies it.
16+
* Typographical errors that cause policies to open different ports or protocols than intended.
17+
18+
The explainability mode provides insights into how each side of a connection is affected by your policy rules. You can quickly identify the configuration mistakes by using the explainability mode.
19+
20+
[discrete]
21+
== Example allowed connections
22+
23+
Consider that you have a Kubernetes cluster with the following components:
24+
25+
* A *Monitoring service* called `monitoring-service` that collects data from various applications.
26+
* A core *Internal application A* called `internal-app-a` that actively exposes monitoring endpoints and needs monitoring.
27+
* A network policy configuration that defines Admin Network Policy (ANP) to `pass` connections from monitoring into namespaces with label `security: internal`, and a specific Network Policy (NP) that explicitly allows connections from `monitoring-service` into `internal-app-a`.
28+
29+
You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/0ac857e19bfab4b281ca9bdfb2bbc5ea319b5065/tests/anp_banp_explain_demo[`netpol-analyzer/tests/anp_banp_explain_demo/`].
30+
31+
To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup.
32+
33+
The explainability output for allowed connections from the `monitoring-service` deployment for such configuration shows:
34+
35+
[source,terminal]
36+
----
37+
Connections between monitoring/monitoring-service[Pod] => internal-apps/internal-app-a[Pod]:
38+
Allowed connections:
39+
Allowed TCP, UDP, SCTP due to the following policies and rules:
40+
Egress (Allowed) due to the system default (Allow all)
41+
Ingress (Allowed)
42+
AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring
43+
NetworkPolicy 'internal-apps/allow-monitoring' allows connections by Ingress rule #1
44+
----
45+
46+
In this example, the connection from `monitoring/monitoring-service` to `internal-apps/internal-app-a` is allowed by the combination of ANP `pass-monitoring` that applies broadly on all namespaces with the label `security: internal` and a more specific NP `internal-apps/allow-monitoring` tailored for `internal-app-a`. The output shows that multiple policies can contribute to allowing a connection.
47+
48+
[discrete]
49+
== Example blocked connections
50+
51+
Consider an isolated data service `isolated-data-service` which denies all external access by default for security reasons.
52+
53+
You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/7ab6bbd421d3d80cbfff7cd1529ff8caf0137fbc/tests/anp_banp_explain_demo_2[`netpol-analyzer/tests/anp_banp_explain_demo_2/`].
54+
55+
To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup.
56+
57+
The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows:
58+
59+
[source,terminal]
60+
----
61+
Connections between monitoring/monitoring-service[Pod] => isolated-apps/isolated-data-service[Pod]:
62+
63+
Denied connections:
64+
Denied TCP, UDP, SCTP due to the following policies and rules:
65+
Egress (Allowed) due to the system default (Allow all)
66+
Ingress (Denied)
67+
AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring
68+
BaselineAdminNetworkPolicy 'default' denies connections by Ingress rule deny-ingress-from-monitoring
69+
----
70+
71+
In this example, the connection to `data/isolated-data-service` is blocked by a combination of ANP with Pass action, and of BANP that denies all connections from `monitoring` by default.

‎operating/build-time-network-policy-tools.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@ include::modules/retrieving-connectivity-mapping-information-from-a-kubernetes-m
6565

6666
* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-map_roxctl-netpol[roxctl netpol connectivity map command options].
6767

68+
include::modules/retrieving-explanations.adoc[leveloffset=+2]
69+
70+
include::modules/understanding-connectivity-explanations.adoc[leveloffset=+3]
71+
6872
include::modules/connectivity-map-output-formats-and-visualizations.adoc[leveloffset=+2]
6973

7074
include::modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)