[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fix DITA errors in operating/build-time-network-policy-tools.adoc

modules/build-time-network-policy-generator-next-steps.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * operating/build-time-network-policy-tools.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="build-time-network-policy-generator-next-steps_{context}"]
+= Next steps
+
+[role="_abstract"]
+After generating the network policies, verify the policies for completeness and accuracy before deploying them.
+
+* After generating the policies, you must inspect them for completeness and accuracy, in case any relevant network address was not specified as expected in the YAML files.
+
+* Most importantly, verify that required connections are not blocked by the isolating policies. To help with this inspection you can use the `roxctl netpol connectivity map` tool.
+
+[NOTE]
+====
+Applying network policies to the cluster as part of the workload deployment using automation saves time and ensures accuracy.
+You can follow a GitOps approach by submitting the generated policies using pull requests, providing the team an opportunity to review the policies before deploying them as part of the pipeline.
+====

modules/build-time-network-policy-generator.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * operating/build-time-network-policy-tools.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="build-time-network-policy-generator_{context}"]
+= Build-time network policy generator
+
+[role="_abstract"]
+The build-time network policy generator can automatically generate Kubernetes network policies based on application YAML manifests. You can use it to develop network policies as part of the continuous integration/continuous deployment (CI/CD) pipeline before deploying applications on your cluster.
+
+Red{nbsp}Hat developed this feature in partnership with the developers of the NP-Guard project.
+First, the build-time network policy generator analyzes Kubernetes manifests in a local folder, including service manifests, config maps, and workload manifests such as `Pod`, `Deployment`, `ReplicaSet`, `Job`, `DaemonSet`, and `StatefulSet`.
+Then, it discovers the required connectivity and creates the Kubernetes network policies to achieve pod isolation.
+These policies allow no more and no less than the needed ingress and egress traffic.

modules/build-time-network-policy-tools-commands.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * operating/build-time-network-policy-tools.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="build-time-network-policy-tools-commands_{context}"]
+= Network policy tools
+
+[role="_abstract"]
+The following table lists the build-time network policy tools available in the `roxctl` CLI.
+
+[%autowidth,options="header"]
+|===
+|Command |Description
+
+|`roxctl netpol generate`
+|Generates Kubernetes network policies by analyzing your project's YAML manifests in a specified directory.
+
+|`roxctl netpol connectivity map`
+|Lists the allowed connections between workloads in your project directory by examining the workload, Kubernetes network policy, ANP, and BANP manifests. You can generate the output in various text formats or in a graphical `.dot` format.
+
+|`roxctl netpol connectivity diff`
+|Creates a list of variations in the allowed connections between two project versions. The workload and Kubernetes network policy, ANP, and BANP manifests in each version's directory decide the variations. This feature shows the semantic differences which are not obvious when performing a source code (syntactic) `diff`.
+
+|===

modules/connectivity-map-output-formats-and-visualizations.adoc

@@ -6,4 +6,5 @@
 [id="connectivity-map-output-formats-and-visualizations_{context}"]
 = Connectivity map output formats and visualizations
 
-You can use various output formats, including `txt`, `md`, `csv`, `json`, and `dot`. The `dot` format is ideal for visualizing the output as a connectivity graph. It can be viewed using graph visualization software such as link:https://graphviz.org/[Graphviz tool], and link:https://www.google.com/search?q=vscode+Graphviz+extension[extensions to VSCode]. You can convert the `dot` output to formats such as `svg`, `jpeg`, or `png` using Graphviz, whether it is installed locally or through an online viewer.
+[role="_abstract"]
+You can use various output formats, including `txt`, `md`, `csv`, `json`, and `dot`. The `dot` format is ideal for visualizing the output as a connectivity graph. You can view it by using graph visualization software such as Graphviz and extensions to VSCode. You can convert the `dot` output to formats such as `svg`, `jpeg`, or `png` by using Graphviz, whether you install it locally or use an online viewer.

modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc

@@ -6,6 +6,7 @@
 [id="connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command_{context}"]
 = Connectivity mapping using the roxctl netpol connectivity map command
 
+[role="_abstract"]
 Connectivity mapping shows you allowed connections between workloads. It uses network policies defined in Kubernetes manifests, including Admin Network Policy (ANP) and Baseline Admin Network Policy (BANP). You can visualize and understand how your Kubernetes workloads communicate based on these combined network policies.
 
 To retrieve connectivity mapping information, the `roxctl netpol connectivity map` command requires a directory path. This directory must contain your Kubernetes network policy, ANP, and BANP manifests. The command's output details the connectivity within the analyzed Kubernetes resources.

modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc

@@ -6,7 +6,10 @@
 [id="distinguishing-between-syntactic-and-semantic-difference-outputs_{context}"]
 = Distinguishing between syntactic and semantic difference outputs
 
-In the following example, `dir1` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`], and `dir2` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[`netpol-diff-example-minimal/`]. The difference between the directories is a small change in the network policy `backend-netpol`.
+[role="_abstract"]
+The following example compares syntactic and semantic difference outputs to show how source code changes affect network connectivity.
+
+In the following example, `dir1` is `netpol-analysis-example-minimal/`, and `dir2` is `netpol-diff-example-minimal/`. The difference between the directories is a small change in the network policy `backend-netpol`.
 
 .Example policy from `dir1`:
 

modules/generating-connectivity-difference-reports.adoc

@@ -24,15 +24,15 @@ $ roxctl netpol connectivity diff --dir1=<folder_path_1> --dir2=<folder_path_2>
 +
 Specify the path to the folders, which can include sub-folders that contain YAML resources and network policies for analysis. The command scans the entire sub-folder trees for both the directories.
 +
-For example, `<folder_path_1>` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`] and `<folder_path_2>` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[`netpol-diff-example-minimal/`]. Optionally, you can also specify parameters to change the behavior of the command.
+For example, `<folder_path_1>` is `netpol-analysis-example-minimal/` and `<folder_path_2>` is `netpol-diff-example-minimal/`. Optionally, you can also specify parameters to change the behavior of the command.
 +
 [NOTE]
 ====
 The command considers all YAML files that you can accept by using `kubectl apply -f`, and the YAML files then become valid inputs for your `roxctl netpol connectivity diff` command.
 ====
 +
-.Example output
-
+The following is an example output:
++
 [cols="1,2,2,1,1,1",options="header"]
 |===
 
@@ -54,8 +54,8 @@ The command considers all YAML files that you can accept by using `kubectl apply
 
 |===
 +
-The semantic difference report gives you an overview of the connections that were changed, added, or removed in `dir2` compared to the connections allowed in `dir1`. When you review the output, each line represents one allowed connection that was added, removed, or changed in `dir2` compared to `dir1`.
+The semantic difference report gives you an overview of the connections that changed, that you added, or that you removed in `dir2` compared to the connections allowed in `dir1`. When you review the output, each line represents one allowed connection that you added, removed, or changed in `dir2` compared to `dir1`.
 +
 If applicable, the `workloads-diff-info` provides additional details about added or removed workloads related to the added or removed connection.
 +
-For example, if a connection from workload `A` to workload `B` is removed because workload `B` was deleted, the `workloads-diff-info` indicates that workload `B` was removed. However, if such a connection was removed only because of network policy changes and neither workload `A` nor `B` was deleted, the `workloads-diff-info` is empty.
+For example, if you remove a connection from workload `A` to workload `B` because you deleted workload `B`, the `workloads-diff-info` indicates that you removed workload `B`. However, if you removed such a connection only because of network policy changes and you did not delete workload `A` or `B`, the `workloads-diff-info` is empty.

modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc

@@ -6,11 +6,12 @@
 [id="generating-svg-graphs-from-the-dot-output-using-graphviz_{context}"]
 = Generating svg graphs from the dot output using Graphviz
 
-Follow these steps to create a graph in `svg` format from the `dot` output.
+[role="_abstract"]
+You can create a graph in `svg` format from the `dot` output by using Graphviz.
 
 .Prerequisites
 
-* link:https://graphviz.org/[Graphviz] is installed on your local system.
+* You have installed Graphviz on your local system.
 
 .Procedure
 
@@ -19,9 +20,4 @@ Follow these steps to create a graph in `svg` format from the `dot` output.
 [source,terminal]
 ----
 $ dot -Tsvg connlist_output.dot > connlist_output_graph.svg
-----
-The following are examples of the dot output and the resulting graph generated by Graphviz:
-
-** link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/connlist/netpol-analysis-example-minimal_connlist_output.dot[Example 1: dot output]
-
-** link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/connlist/netpol-analysis-example-minimal_connlist_output.dot.svg[Example 2: Graph generated by Graphviz]
+----

modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc

@@ -7,6 +7,7 @@
 [id="identifying-the-differences-in-allowed-connections-between-project-versions_{context}"]
 = Identifying the differences in allowed connections between project versions
 
+[role="_abstract"]
 The `roxctl netpol connectivity diff` command identifies differences in allowed connections between two project versions. It analyzes network policy, Admin Network Policy (ANP), and Baseline Admin Network Policy (BANP) manifests in each version's directory. This analysis provides a text-based report of the differences. It also includes the impact of ANP and BANP resources, giving you a complete view of policy changes across cluster scopes.
 
 You can view connectivity difference reports in a variety of output formats, including `text`, `md`, `dot`, and `csv`.

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

@@ -21,10 +21,11 @@ roxctl netpol connectivity map <folder_path> [flags]
 where:
 +
 --
-`<folder_path>`:: Specifies the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis, for example, link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`]. The command scans the entire sub-folder tree. Optionally, you can also specify parameters to modify the behavior of the command.
+`<folder_path>`:: Specifies the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis, for example, `netpol-analysis-example-minimal/`. The command scans the entire sub-folder tree. Optionally, you can also specify parameters to change the behavior of the command.
 --
 +
-.Example output
+The following is an example output:
++
 [cols="2,2,1",options="header"]
 |===
 
@@ -45,7 +46,7 @@ where:
 |===
 +
 The output displays a table listing the allowed connectivity lines.
-Each line is composed of the following elements:
+Each line has the following elements:
 
 `src`:: Represents the source endpoint.
 `dst`:: Represents the destination endpoint.

modules/retrieving-explanations.adoc

@@ -7,7 +7,7 @@
 = Retrieving explanations
 
 [role="_abstract"]
-You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations.
+You can understand why your Kubernetes network policy rules allow or deny connections by retrieving the explanations.
 
 .Procedure
 

modules/semantic-difference-output.adoc

@@ -6,6 +6,9 @@
 [id="semantic-difference-output_{context}"]
 = Semantic difference output
 
+[role="_abstract"]
+You can analyze the connectivity differences between Kubernetes manifests and network policies in two directories to see the semantic differences.
+
 .Procedure
 
 * Run the following command to analyze the connectivity differences between the Kubernetes manifests and network policies in the two specified directories:
@@ -15,7 +18,7 @@
 $ roxctl netpol connectivity diff --dir1=roxctl/netpol/connectivity/diff/testdata/netpol-analysis-example-minimal/ --dir2=roxctl/netpol/connectivity/diff/testdata/netpol-diff-example-minimal
 ----
 +
-.Example output
+The following is an example output:
 +
 [source,text,subs="+quotes"]
 ----

modules/syntactic-difference-output.adoc

@@ -6,6 +6,9 @@
 [id="syntactic-difference-output_{context}"]
 = Syntactic difference output
 
+[role="_abstract"]
+You can compare the contents of YAML files in two directories to see the syntactic differences.
+
 .Procedure
 
 * Run the following command to compare the contents of the `netpols.yaml` files in the two specified directories:
@@ -14,7 +17,7 @@
 $ diff netpol-diff-example-minimal/netpols.yaml netpol-analysis-example-minimal/netpols.yaml
 ----
 +
-.Example output
+The following is an example output:
 +
 [source,text,subs="+quotes"]
 ----

modules/understanding-connectivity-explanations-allowed.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * operating/build-time-network-policy-tools.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="understanding-connectivity-explanations-allowed_{context}"]
+= Example allowed connections
+
+[role="_abstract"]
+The following example shows the explainability output for allowed connections between a monitoring service and an internal application.
+
+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 the `netpol-analyzer/tests/anp_banp_explain_demo/` directory.
+
+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:
+
+The following is an example output:
+[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 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` allows the connection from `monitoring/monitoring-service` to `internal-apps/internal-app-a`. The output shows that many policies can contribute to allowing a connection.

modules/understanding-connectivity-explanations-blocked.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * operating/build-time-network-policy-tools.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="understanding-connectivity-explanations-blocked_{context}"]
+= Example blocked connections
+
+[role="_abstract"]
+The following example shows the explainability output for blocked connections to an isolated data service.
+
+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 the `netpol-analyzer/tests/anp_banp_explain_demo_2/` directory.
+
+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:
+
+The following is an example output:
++
+[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, a combination of ANP with Pass action and BANP that denies all connections from `monitoring` by default blocks the connection to `data/isolated-data-service`.