Skip to content

[RHACS] Added docs for explanations feature #95065

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -49,3 +49,7 @@ Each line is composed of the following elements:
* `conn`:: Represents the permissible connectivity attributes.
An endpoint follows the format `namespace/name[Kind]`. For example, `default/backend[Deployment]`.

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.
You can use the output to debug network policy configurations.
For more information about understanding the explanation output, see "Retriving explanations".
23 changes: 23 additions & 0 deletions modules/retrieving-explanations.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
// Module included in the following assemblies:
//
// * operating/build-time-network-policy-tools.adoc

:_mod-docs-content-type: PROCEDURE
[id="retrieving-explanations_{context}"]
= Retrieving explanations

[role="_abstract"]
You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations.

.Procedure

* To generate a connectivity report with explanations, run the following command:
+
[source,terminal,subs="+quotes"]
----
$ roxctl netpol connectivity map --explain <folder_path> <1>
----
+
<1> Specify the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis.
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.
3 changes: 3 additions & 0 deletions modules/roxctl-netpol-connectivity-map-command-options.adoc
Original file line number Diff line number Diff line change
@@ -13,6 +13,9 @@ The `roxctl netpol connectivity map` command supports the following options:

|Option |Description

|`--explain`
|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format.

Comment on lines +16 to +18
Copy link
Contributor Author

@gaurav-nelson gaurav-nelson Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: For peer review, please ignore this change. It is the actual output from the CLI tool.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question about this change:
why can't I see this update in the link for the table options here?

Also, why in this link the --exposure option exists, but not in the table of this changed file?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @adisos this was an older file which we don't use anywhere. I've updated the correct file n my recent commit to fix it.

|`--fail`
|Fail on the first encountered error. The default value is `false`.

8 changes: 7 additions & 1 deletion modules/roxctl-netpol-connectivity-map.adoc
Original file line number Diff line number Diff line change
@@ -21,7 +21,10 @@ $ roxctl netpol connectivity map <folder_path> [flags] <1>
|===
|Option |Description

|`--exposure`
|`--explain`
|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format.

|`--exposure`
|Enhance the analysis of permitted connectivity by using exposure analysis. The default value is `false`.

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

|`-h`, `--help`
|View the help text for the `roxctl netpol connectivity map` command.

|`-o`, `--output-format string`
|Configure the connections list in a specific format. Supported formats include `txt`, `json`, `md`, `dot`, and `csv`. The default value is `txt`.

73 changes: 73 additions & 0 deletions modules/understanding-connectivity-explanations.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
// Module included in the following assemblies:
//
// * operating/build-time-network-policy-tools.adoc

:_mod-docs-content-type: CONCEPT
[id="understanding-connectivity-explanations_{context}"]
= Understanding Connectivity Explanations

[role="_abstract"]
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.
You can debug and refine your network policies by using the explainability mode which provides additional details beyond the standard connectivity report.

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 allow the connection.

The following are examples of some common issues:

* Mismatched ingress and egress rules, where one side of a connection allows traffic but the other denies it.
* Typographical errors that cause policies to open different ports or protocols than intended.
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.

[discrete]
== Example allowed connections

Consider that you have a Kubernetes cluster with the following components:

* A *Monitoring service* called `monitoring-service` that collects data from various applications.
* A core *Internal application A* called `internal-app-a` that actively exposes monitoring endpoints and needs monitoring.
* 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`.

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/`].

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.

The explainability output for allowed connections from the `monitoring-service` deployment for such configuration shows:

[source,terminal]
----
Connections between monitoring/monitoring-service[Pod] => internal-apps/internal-app-a[Pod]:
Allowed connections:
Allowed TCP, UDP, SCTP due to the following policies and rules:
Egress (Allowed) due to the system default (Allow all)
Ingress (Allowed)
AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring
NetworkPolicy 'internal-apps/allow-monitoring' allows connections by Ingress rule #1
----

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.

[discrete]
== Example blocked connections

Consider an isolated data service `isolated-data-service` which denies all external access by default for security reasons.

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/`].

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.

The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows:

[source,terminal]
----
Connections between monitoring/monitoring-service[Pod] => isolated-apps/isolated-data-service[Pod]:
Denied connections:
Denied TCP, UDP, SCTP due to the following policies and rules:
Egress (Allowed) due to the system default (Allow all)
Ingress (Denied)
AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring
BaselineAdminNetworkPolicy 'default' denies connections by Ingress rule deny-ingress-from-monitoring
----

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.
4 changes: 4 additions & 0 deletions operating/build-time-network-policy-tools.adoc
Original file line number Diff line number Diff line change
@@ -65,6 +65,10 @@ include::modules/retrieving-connectivity-mapping-information-from-a-kubernetes-m

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

include::modules/retrieving-explanations.adoc[leveloffset=+2]

include::modules/understanding-connectivity-explanations.adoc[leveloffset=+3]

include::modules/connectivity-map-output-formats-and-visualizations.adoc[leveloffset=+2]

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