[RHACS] Added docs for explanations feature #95065

gaurav-nelson · 2025-06-23T05:28:13Z

For https://issues.redhat.com/browse/ROX-29787

Added documentation for the new explainability feature.

Cherrypick in rhacs-docs-4.8.

Preview:

ocpdocs-previewbot · 2025-06-23T05:32:38Z

🤖 Thu Jun 26 11:51:34 - Prow CI generated the docs preview:

https://95065--ocpdocs-pr.netlify.app/
https://95065--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-netpol.html
https://95065--ocpdocs-pr.netlify.app/openshift-acs/latest/operating/build-time-network-policy-tools.html

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

gaurav-nelson · 2025-06-23T09:06:34Z

modules/retrieving-explanations.adoc

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


question: Can we simplify this word. Get or Fetch maybe?

I think we can leave it as it is.

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

modules/retrieving-explanations.adoc

modules/understanding-connectivity-explanations.adoc

adisos

adding comments for updating examples text and with links to actual YAML configurations.

modules/understanding-connectivity-explanations.adoc

gaurav-nelson · 2025-06-25T06:46:34Z

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

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


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

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?

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.

adisos

Looks good, added one more question.

adisos · 2025-06-26T04:31:58Z

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

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


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?

agantony

Highlighted a few issues; overall lgtm!

agantony · 2025-06-26T10:18:12Z

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

@@ -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]`.
+
+Additionally, you can also use the `--explain` option with the `roxctl netpol connectivity map` command to see which policies and rules are responsible for allowing or denying specific connections.


Suggested change

Additionally, you can also use the `--explain` option with the `roxctl netpol connectivity map` command to see which policies and rules are responsible for allowing or denying specific connections.

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.

https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps

agantony · 2025-06-26T10:18:53Z

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

@@ -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]`.
+
+Additionally, you can also use the `--explain` option with the `roxctl netpol connectivity map` command to see which policies and rules are responsible for allowing or denying specific connections.
+The output is useful for debugging network policy configurations.


Suggested change

The output is useful for debugging network policy configurations.

You can use the output to debug network policy configurations.

agantony · 2025-06-26T10:19:55Z

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

+
+Additionally, you can also use the `--explain` option with the `roxctl netpol connectivity map` command to see which policies and rules are responsible for allowing or denying specific connections.
+The output is useful for debugging network policy configurations.
+For more information on understanding the explanation output, see "Retriving explanations" section.


Suggested change

For more information on understanding the explanation output, see "Retriving explanations" section.

For more information about understanding the explanation output, see "Retriving explanations".

https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#lead-in-link-sentences

agantony · 2025-06-26T10:22:00Z

modules/retrieving-explanations.adoc

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


I think we can leave it as it is.

agantony · 2025-06-26T10:23:00Z

modules/retrieving-explanations.adoc

+= Retrieving explanations
+
+[role="_abstract"]
+Understand why connections are allowed or denied based on your Kubernetes network policy rules.


Suggested change

Understand why connections are allowed or denied based on your Kubernetes network policy rules.

You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations.

agantony · 2025-06-26T11:39:28Z

modules/understanding-connectivity-explanations.adoc

+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.


Suggested change

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.

In this example, the combination of ANP `pass-monitoring` allows the connection from `monitoring/monitoring-service` to `internal-apps/internal-app-a` 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.

agantony · 2025-06-26T11:41:57Z

modules/understanding-connectivity-explanations.adoc

+[discrete]
+== Example blocked connections
+
+Consider an isolated data service `isolated-data-service` which is designed to deny all external access by default for security reasons.


Suggested change

Consider an isolated data service `isolated-data-service` which is designed to deny all external access by default for security reasons.

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

agantony · 2025-06-26T11:42:18Z

modules/understanding-connectivity-explanations.adoc

+
+Consider an isolated data service `isolated-data-service` which is designed to deny 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/`].


No GitHub refs.

agantony · 2025-06-26T11:43:01Z

modules/understanding-connectivity-explanations.adoc

+
+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/`].
+
+The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows:


Suggested change

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

When you run the `roxctl netpol connectivity map --explain` command, you can see the following example explainability output for allowed connections from the `monitoring-service` deployment for such a configuration:

agantony · 2025-06-26T11:45:42Z

modules/understanding-connectivity-explanations.adoc

+	        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.


Suggested change

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.

In this example, a combination of ANP with Pass action blocks the connection to `data/isolated-data-service`, and of BANP that denies all connections from `monitoring` by default.

The ANP with Pass action does not block the connection, it only delegates the decision to the next policies layer, which in this case is the BANP. I would keep the original wording, that the combination of ANP with BANP results in a blocked connection for this case.

openshift-ci · 2025-06-26T11:53:21Z

@gaurav-nelson: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

gaurav-nelson added RHACS Label for RHACS related PRs that go in the rhacs-docs branch rhacs-docs-4.8 labels Jun 23, 2025

openshift-ci bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jun 23, 2025

gaurav-nelson added the peer-review-needed Signifies that the peer review team needs to review this PR label Jun 23, 2025

gaurav-nelson commented Jun 23, 2025

View reviewed changes

modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc Outdated Show resolved Hide resolved

gaurav-nelson commented Jun 23, 2025

View reviewed changes

modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc Outdated Show resolved Hide resolved

gaurav-nelson commented Jun 23, 2025

View reviewed changes

gaurav-nelson removed the peer-review-needed Signifies that the peer review team needs to review this PR label Jun 23, 2025

adisos suggested changes Jun 23, 2025

View reviewed changes

adisos reviewed Jun 23, 2025

View reviewed changes

gaurav-nelson force-pushed the ROX-25000-np-guard-explainability branch from bc60026 to 8d264c0 Compare June 25, 2025 06:39

gaurav-nelson added the peer-review-needed Signifies that the peer review team needs to review this PR label Jun 25, 2025

gaurav-nelson requested a review from adisos June 25, 2025 06:44

gaurav-nelson commented Jun 25, 2025

View reviewed changes

adisos reviewed Jun 26, 2025

View reviewed changes

agantony added peer-review-in-progress Signifies that the peer review team is reviewing this PR and removed peer-review-needed Signifies that the peer review team needs to review this PR labels Jun 26, 2025

Added docs for explanations

0698656

gaurav-nelson force-pushed the ROX-25000-np-guard-explainability branch from 8d264c0 to 0698656 Compare June 26, 2025 11:44

agantony reviewed Jun 26, 2025

View reviewed changes

agantony added peer-review-done Signifies that the peer review team has reviewed this PR and removed peer-review-in-progress Signifies that the peer review team is reviewing this PR labels Jun 26, 2025

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

	Additionally, you can also use the `--explain` option with the `roxctl netpol connectivity map` command to see which policies and rules are responsible for allowing or denying specific connections.
	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.

	The output is useful for debugging network policy configurations.
	You can use the output to debug network policy configurations.

	For more information on understanding the explanation output, see "Retriving explanations" section.
	For more information about understanding the explanation output, see "Retriving explanations".

	Understand why connections are allowed or denied based on your Kubernetes network policy rules.
	You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations.

		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.

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


		Consider an isolated data service `isolated-data-service` which is designed to deny 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/`].


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

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

	The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows:
	When you run the `roxctl netpol connectivity map --explain` command, you can see the following example explainability output for allowed connections from the `monitoring-service` deployment for such a configuration:

	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.
	In this example, a combination of ANP with Pass action blocks the connection to `data/isolated-data-service`, and of BANP that denies all connections from `monitoring` by default.

[RHACS] Added docs for explanations feature #95065

Are you sure you want to change the base?

[RHACS] Added docs for explanations feature #95065

Conversation

gaurav-nelson commented Jun 23, 2025

Uh oh!

ocpdocs-previewbot commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adisos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaurav-nelson Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adisos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agantony left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Jun 26, 2025

Uh oh!

Uh oh!

ocpdocs-previewbot commented Jun 23, 2025 •

edited

Loading

gaurav-nelson Jun 25, 2025 •

edited

Loading