diff --git a/modules/build-time-network-policy-generator-next-steps.adoc b/modules/build-time-network-policy-generator-next-steps.adoc new file mode 100644 index 000000000000..c660ae093f8d --- /dev/null +++ b/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. +==== diff --git a/modules/build-time-network-policy-generator.adoc b/modules/build-time-network-policy-generator.adoc new file mode 100644 index 000000000000..d371a5964396 --- /dev/null +++ b/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. diff --git a/modules/build-time-network-policy-tools-commands.adoc b/modules/build-time-network-policy-tools-commands.adoc new file mode 100644 index 000000000000..c3c78cfb10c2 --- /dev/null +++ b/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`. + +|=== diff --git a/modules/connectivity-map-output-formats-and-visualizations.adoc b/modules/connectivity-map-output-formats-and-visualizations.adoc index fb16bebb1f8f..f8663372bdd0 100644 --- a/modules/connectivity-map-output-formats-and-visualizations.adoc +++ b/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. \ No newline at end of file +[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. \ No newline at end of file diff --git a/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc b/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc index 36e89ead890c..5b3244b2b186 100644 --- a/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc +++ b/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. \ No newline at end of file diff --git a/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc b/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc index e4c18e67a5cc..eadfb502ca0c 100644 --- a/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc +++ b/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`: diff --git a/modules/generating-connectivity-difference-reports.adoc b/modules/generating-connectivity-difference-reports.adoc index a35dc1e07d45..c2ec15383d66 100644 --- a/modules/generating-connectivity-difference-reports.adoc +++ b/modules/generating-connectivity-difference-reports.adoc @@ -24,15 +24,15 @@ $ roxctl netpol connectivity diff --dir1= --dir2= + 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, `` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`] and `` 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, `` is `netpol-analysis-example-minimal/` and `` 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc b/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc index 365774e1c2e6..df1796c40f87 100644 --- a/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc +++ b/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] \ No newline at end of file +---- \ No newline at end of file diff --git a/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc b/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc index b9aa155050a3..96db6c77816f 100644 --- a/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc +++ b/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`. \ No newline at end of file diff --git a/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc index 9ad0f535348b..ddc4213e2a76 100644 --- a/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc +++ b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc @@ -21,10 +21,11 @@ roxctl netpol connectivity map [flags] where: + -- -``:: 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. +``:: 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. diff --git a/modules/retrieving-explanations.adoc b/modules/retrieving-explanations.adoc index 2b5220350476..16b25469b685 100644 --- a/modules/retrieving-explanations.adoc +++ b/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 diff --git a/modules/semantic-difference-output.adoc b/modules/semantic-difference-output.adoc index 973e2f5d875c..7ee451e56601 100644 --- a/modules/semantic-difference-output.adoc +++ b/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"] ---- diff --git a/modules/syntactic-difference-output.adoc b/modules/syntactic-difference-output.adoc index 643e179dc83f..4fb574138d27 100644 --- a/modules/syntactic-difference-output.adoc +++ b/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"] ---- diff --git a/modules/understanding-connectivity-explanations-allowed.adoc b/modules/understanding-connectivity-explanations-allowed.adoc new file mode 100644 index 000000000000..65b00c9f1d01 --- /dev/null +++ b/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. diff --git a/modules/understanding-connectivity-explanations-blocked.adoc b/modules/understanding-connectivity-explanations-blocked.adoc new file mode 100644 index 000000000000..e4da9e61c447 --- /dev/null +++ b/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`. diff --git a/modules/understanding-connectivity-explanations.adoc b/modules/understanding-connectivity-explanations.adoc index ba85d2f91a72..adda74968f2e 100644 --- a/modules/understanding-connectivity-explanations.adoc +++ b/modules/understanding-connectivity-explanations.adoc @@ -10,60 +10,11 @@ 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. +As a developer or DevOps professional, you might meet situations where a connection you expect to be open fails, 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. - -== 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. - -== 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. \ No newline at end of file +The explainability mode provides insights into how your policy rules affect each side of a connection. You can quickly identify the configuration mistakes by using the explainability mode. \ No newline at end of file diff --git a/modules/using-the-build-time-network-policy-generator.adoc b/modules/using-the-build-time-network-policy-generator.adoc index 55a3d9ebcf6a..c349d3622bb9 100644 --- a/modules/using-the-build-time-network-policy-generator.adoc +++ b/modules/using-the-build-time-network-policy-generator.adoc @@ -1,12 +1,12 @@ // Module included in the following assemblies: // -// * manage-network-policies/build-time-network-policies.adoc +// * operating/build-time-network-policy-tools.adoc :_mod-docs-content-type: PROCEDURE [id="using-the-build-time-network-policy-generator_{context}"] = Using the build-time network policy generator [role="_abstract"] -The build-time network policy generator is included in the `roxctl` CLI. +The `roxctl` CLI includes the build-time network policy generator. For the build-time network policy generation feature, `roxctl` CLI does not need to communicate with {product-title-short} Central so you can use it in any development environment. .Prerequisites @@ -15,9 +15,9 @@ Therefore, before you run the command, you must already have service manifests, . Verify that you can apply these YAML files by using the `kubectl apply -f` command. The build-time network policy generator does not work with files that use Helm style templating. . Verify that the service network addresses are not hard-coded. Every workload that needs to connect to a service must specify the service network address as a variable. You can specify this variable by using the workload's resource environment variable or in a config map. -** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/k8s_guestbook/frontend-deployment.yaml#L25:L28[Example 1: Using an environment variable] -** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L105:L109[Example 2: Using a config map] -** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L269:L271[Example 3: Using a config map] +** Example 1: Using an environment variable +** Example 2: Using a config map +** Example 3: Using a config map . Service network addresses must match the following official regular expression pattern: + ---- diff --git a/operating/build-time-network-policy-tools.adoc b/operating/build-time-network-policy-tools.adoc index 84f66450ee74..4111404f74a9 100644 --- a/operating/build-time-network-policy-tools.adoc +++ b/operating/build-time-network-policy-tools.adoc @@ -7,88 +7,111 @@ include::modules/common-attributes.adoc[] toc::[] [role="_abstract"] -Build-time network policy tools let you automate the creation and validation of network policies, including Kubernetes network policies, and the cluster-wide Admin Network Policy (ANP) and Baseline Admin Network Policy (BANP), in your development and operations workflows by using the `roxctl` CLI. These tools work with a specified file directory containing your project's workload and network policy manifests and do not require {product-title-short} authentication. +You can use build-time network policy tools to automate the creation and validation of network policies, including Kubernetes network policies, and the cluster-wide Admin Network Policy (ANP) and Baseline Admin Network Policy (BANP), in your development and operations workflows by using the `roxctl` CLI. These tools work with a specified file directory containing your project's workload and network policy manifests and do not require {product-title-short} authentication. -.Network policy tools -[%autowidth,options="header"] -|=== -|Command |Description +//Network policy tools commands +include::modules/build-time-network-policy-tools-commands.adoc[leveloffset=+1] -|`roxctl netpol generate` -|Generates Kubernetes network policies by analyzing your project's YAML manifests in a specified directory. For more information, see xref:../operating/build-time-network-policy-tools.adoc#using-the-build-time-network-policy-generator_network-policy-tools[Using the build-time network policy generator]. - -|`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. For more information, see xref:../operating/build-time-network-policy-tools.adoc#connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command_network-policy-tools[Connectivity mapping using the roxctl netpol connectivity map command]. - -|`roxctl netpol connectivity diff` -|Creates a list of variations in the allowed connections between two project versions. This is determined by the workload and Kubernetes network policy, ANP, and BANP manifests in each version's directory. This feature shows the semantic differences which are not obvious when performing a source code (syntactic) `diff`. For more information, see xref:../operating/build-time-network-policy-tools.adoc#identifying-the-differences-in-allowed-connections-between-project-versions_network-policy-tools[Identifying the differences in allowed connections between project versions]. - -|=== - -//Network policy generator -[id="build-time-network-policy-generator_{context}"] -== Build-time network policy generator +[role="_additional-resources"] +.Additional resources +* xref:../operating/build-time-network-policy-tools.adoc#using-the-build-time-network-policy-generator_network-policy-tools[Using the build-time network policy generator] +* xref:../operating/build-time-network-policy-tools.adoc#connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command_network-policy-tools[Connectivity mapping using the roxctl netpol connectivity map command] +* xref:../operating/build-time-network-policy-tools.adoc#identifying-the-differences-in-allowed-connections-between-project-versions_network-policy-tools[Identifying the differences in allowed connections between project versions] -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. +//Build-time network policy generator +include::modules/build-time-network-policy-generator.adoc[leveloffset=+1] -Red{nbsp}Hat developed this feature in partnership with the developers of the link:https://np-guard.github.io/[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. +[role="_additional-resources"] +.Additional resources +* link:https://np-guard.github.io/[NP-Guard project] +//Using the build-time network policy generator include::modules/using-the-build-time-network-policy-generator.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-generate_roxctl-netpol[roxctl netpol generate command options] +* link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/k8s_guestbook/frontend-deployment.yaml#L25:L28[Example 1: Using an environment variable] +* link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L105:L109[Example 2: Using a config map] +* link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L269:L271[Example 3: Using a config map] -* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-generate_roxctl-netpol[roxctl netpol generate command options]. +//Next steps after generating policies +include::modules/build-time-network-policy-generator-next-steps.adoc[leveloffset=+2] -.Next steps - -* 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. -==== - -//Connectivity mapping +//Connectivity mapping using the roxctl netpol connectivity map command include::modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc[leveloffset=+1] +//Retrieving connectivity mapping information from a Kubernetes manifest directory include::modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-map_roxctl-netpol[roxctl netpol connectivity map command options] +* link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[netpol-analysis-example-minimal] -* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-map_roxctl-netpol[roxctl netpol connectivity map command options]. - +//Retrieving explanations include::modules/retrieving-explanations.adoc[leveloffset=+2] +//Understanding connectivity explanations include::modules/understanding-connectivity-explanations.adoc[leveloffset=+3] +//Example allowed connections +include::modules/understanding-connectivity-explanations-allowed.adoc[leveloffset=+4] + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/np-guard/netpol-analyzer/tree/0ac857e19bfab4b281ca9bdfb2bbc5ea319b5065/tests/anp_banp_explain_demo[netpol-analyzer/tests/anp_banp_explain_demo] + +//Example blocked connections +include::modules/understanding-connectivity-explanations-blocked.adoc[leveloffset=+4] + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/np-guard/netpol-analyzer/tree/7ab6bbd421d3d80cbfff7cd1529ff8caf0137fbc/tests/anp_banp_explain_demo_2[netpol-analyzer/tests/anp_banp_explain_demo_2] + +//Connectivity map output formats and visualizations include::modules/connectivity-map-output-formats-and-visualizations.adoc[leveloffset=+2] +[role="_additional-resources"] +.Additional resources +* link:https://graphviz.org/[Graphviz] +* link:https://www.google.com/search?q=vscode+Graphviz+extension[VSCode Graphviz extensions] + +//Generating SVG graphs from the dot output using Graphviz include::modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc[leveloffset=+2] -//Connectivity diff +[role="_additional-resources"] +.Additional resources +* link:https://graphviz.org/[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] + +//Identifying the differences in allowed connections between project versions include::modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc[leveloffset=+1] +//Generating connectivity difference reports include::modules/generating-connectivity-difference-reports.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources - -* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-diff_roxctl-netpol[roxctl netpol connectivity diff command options]. +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-diff_roxctl-netpol[roxctl netpol connectivity diff command options] +* link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[netpol-analysis-example-minimal] +* link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[netpol-diff-example-minimal] * link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.txt[Output generated by the `roxctl netpol connectivity diff` command. Example 1: text format] * link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.md[Output generated by the `roxctl netpol connectivity diff` command. Example 2: md format] * link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.dot.svg[Output generated by the `roxctl netpol connectivity diff` command. Example 3: svg graph generated from dot format] * link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.csv[Output generated by the `roxctl netpol connectivity diff` command. Example 4: csv format] +//Distinguishing between syntactic and semantic difference outputs include::modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc[leveloffset=+2] +[role="_additional-resources"] +.Additional resources +* link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[netpol-analysis-example-minimal] +* link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[netpol-diff-example-minimal] + +//Syntactic difference output include::modules/syntactic-difference-output.adoc[leveloffset=+3] -include::modules/semantic-difference-output.adoc[leveloffset=+3] \ No newline at end of file +//Semantic difference output +include::modules/semantic-difference-output.adoc[leveloffset=+3]