-
Notifications
You must be signed in to change notification settings - Fork 1.8k
[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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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. |
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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Question about this change: Also, why in this link the There was a problem hiding this comment. Choose a reason for hiding this commentThe 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`. | ||
|
||
|
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 | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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`. | ||
|
||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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/`]. | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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: | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
[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/`]. | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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: | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
[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. | ||
gaurav-nelson marked this conversation as resolved.
Show resolved
Hide resolved
|
Uh oh!
There was an error while loading. Please reload this page.