Chapter 8. Build-time network policy tools Build-time network policy tools let you automate the creation and validation of Kubernetes network policies in your development and operations workflows 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 RHACS authentication. Table 8.1. Network policy tools Command Description roxctl netpol generate Generates Kubernetes network policies by analyzing your project's YAML manifests in a specified directory. For more information, see 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 and Kubernetes network policy manifests. You can generate the output in various text formats or in a graphical .dot format. For more information, see 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 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 Identifying the differences in allowed connections between project versions . 8.1. Using the build-time network policy generator 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 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. 8.1.1. Generating build-time network policies The build-time network policy generator is included in the roxctl CLI. For the build-time network policy generation feature, roxctl CLI does not need to communicate with RHACS Central so you can use it in any development environment. Prerequisites The build-time network policy generator recursively scans the directory you specify when you run the command. Therefore, before you run the command, you must already have service manifests, config maps, and workload manifests such as Pod , Deployment , ReplicaSet , Job , DaemonSet , and StatefulSet as YAML files in the specified directory. Verify that you can apply these YAML files as-is 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. 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: 1 In this pattern, <svc> is the service name. <ns> is the namespace where you defined the service. <portNum> is the exposed service port number. Following are some examples that match the pattern: wordpress-mysql:3306 redis-follower.redis.svc.cluster.local:6379 redis-leader.redis http://rating-service. Procedure Verify that the build-time network policy generation feature is available by running the help command: USD roxctl netpol generate -h Generate the policies by using the netpol generate command: USD roxctl netpol generate <folder_path> [flags] 1 1 Specify the path to the folder, which can include sub-folders that contain YAML resources for analysis. The command scans the entire sub-folder tree. Optionally, you can also specify parameters to modify the behavior of the command. For more information about optional parameters, see roxctl netpol generate command options . 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. 8.1.2. roxctl netpol generate command options The roxctl netpol generate command supports the following options: Option Description -h, --help View the help text for the netpol command. -d, --output-dir <dir> Save the generated policies into a target folder. One file per policy. -f, --output-file <filename> Save and merge the generated policies into a single YAML file. --fail Fail on the first encountered error. The default value is false . --remove Remove the output path if it already exist. --strict Treat warnings as errors. The default value is false . 8.2. Connectivity mapping using the roxctl netpol connectivity map command Connectivity mapping provides details on the allowed connections between different workloads based on network policies defined in Kubernetes manifests. You can visualize and understand how different workloads in your Kubernetes environment are allowed to communicate with each other according to the network policies you set up. To retrieve connectivity mapping information, the roxctl netpol connectivity map command requires a directory path that contains Kubernetes workloads and network policy manifests. The output provides details about connectivity details within the Kubernetes resources analyzed. 8.2.1. Retrieving connectivity mapping information from a Kubernetes manifest directory Procedure Run the following command to retrieve the connectivity mapping information: USD roxctl netpol connectivity map <folder_path> [flags] 1 1 Specify 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 modify the behavior of the command. For more information about optional parameters, see roxctl netpol connectivity map command options . Example 8.1. Example output src dst conn 0.0.0.0-255.255.255.255 default/frontend[Deployment] TCP 8080 default/frontend[Deployment] 0.0.0.0-255.255.255.255 UDP 53 default/frontend[Deployment] default/backend[Deployment] TCP 9090 The output shows you a table with a list of allowed connectivity lines. Each connectivity line consists of three parts: source ( src ), destination ( dst ), and allowed connectivity attributes ( conn ). You can interpret src as the source endpoint, dst as the destination endpoint, and conn as the allowable connectivity attributes. An endpoint has the format namespace/name[Kind] , for example, default/backend[Deployment] . 8.2.2. 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 Graphviz tool , and 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. 8.2.3. Generating svg graphs from the dot output using Graphviz Follow these steps to create a graph in svg format from the dot output. Prerequisites Graphviz is installed on your local system. Procedure Run the following command to create the graph in svg format: USD dot -Tsvg connlist_output.dot > connlist_output_graph.svg The following are examples of the dot output and the resulting graph generated by Graphviz: Example 1: dot output Example 2: Graph generated by Graphviz 8.2.4. roxctl netpol connectivity map command options The roxctl netpol connectivity map command supports the following options: Option Description --fail Fail on the first encountered error. The default value is false . --focus-workload string Focus on connections of a specified workload name in the output. -h , --help View the help text for the roxctl netpol connectivity map command. -f , --output-file string Save the connections list output into a specific file. -o , --output-format string Configure the output format. The supported formats are txt , json , md , dot , and csv . The default value is txt . --remove Remove the output path if it already exists. The default value is false . --save-to-file Save the connections list output into a default file. The default value is false . --strict Treat warnings as errors. The default value is false . 8.3. Identifying the differences in allowed connections between project versions This command helps you understand the differences in allowed connections between two project versions. It analyses the workload and Kubernetes network policy manifests located in each version's directory and creates a representation of the differences in text format. You can view connectivity difference reports in a variety of output formats, including text , md , dot , and csv . 8.3.1. Generating connectivity difference reports with the roxctl netpol connectivity diff command To produce a connectivity difference report, the roxctl netpol connectivity diff command requires two folders, dir1 and dir2 , each containing Kubernetes manifests, including network policies. Procedure Run the following command to determine the connectivity differences between the Kubernetes manifests in the specified directories: USD roxctl netpol connectivity diff --dir1= <folder_path_1> --dir2= <folder_path_2> [flags] 1 1 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 netpol-analysis-example-minimal/ and <folder_path_2> is netpol-diff-example-minimal/ . Optionally, you can also specify parameters to modify the behavior of the command. For more information about optional parameters, see roxctl netpol connectivity diff command options . Note The command considers all YAML files that you can accept using kubectl apply -f , and then these become valid inputs for your roxctl netpol connectivity diff command. Example 8.2. Example output diff-type source destination dir 1 dir 2 workloads-diff-info changed default/frontend[Deployment] default/backend[Deployment] TCP 9090 TCP 9090,UDP 53 added 0.0.0.0-255.255.255.255 default/backend[Deployment] No Connections TCP 9090 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 following are example outputs generated by the roxctl netpol connectivity diff command in various formats: Example 1: text format Example 2: md format Example 3: svg graph generated from dot format Example 4: csv format 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. 8.3.2. roxctl netpol connectivity diff command options The roxctl netpol connectivity diff command supports the following options: Option Description --dir1 string First directory path of the input resources. This is a mandatory option. --dir2 string Second directory path of the input resources to be compared with the first directory path. This is a mandatory option. --fail Fail on the first encountered error. The default value is false . -h , --help View the help text for the roxctl netpol connectivity diff command. -f , --output-file string Save the connections difference output into a specific file. -o , --output-format string Configure the output format. The supported formats are txt , md , dot , and csv . The default value is txt . --remove Remove the output path if it already exists. The default value is false . --save-to-file Save the connections difference output into default a file. The default value is false . --strict Treat warnings as errors. The default value is false . 8.3.3. Distinguishing between syntactic and semantic difference outputs 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 : apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: creationTimestamp: null name: backend-netpol spec: ingress: - from: - podSelector: matchLabels: app: frontend ports: - port: 9090 protocol: TCP podSelector: matchLabels: app: backendservice policyTypes: - Ingress - Egress status: {} The change in dir2 is an added - before the ports attribute, which produces a difference output. 8.3.3.1. Syntactic difference output Procedure Run the following command to compare the contents of the netpols.yaml files in the two specified directories: Example output 12c12 < - ports: --- > ports: 8.3.3.2. Semantic difference output Procedure Run the following command to analyze the connectivity differences between the Kubernetes manifests and network policies in the two specified directories: USD 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 Connectivity diff: diff-type: changed, source: default/frontend[Deployment], destination: default/backend[Deployment], dir1: TCP 9090, dir2: TCP 9090,UDP 53 diff-type: added, source: 0.0.0.0-255.255.255.255, destination: default/backend[Deployment], dir1: No Connections, dir2: TCP 9090

Commands:
(http(s)?://)?<svc>(.<ns>(.svc.cluster.local)?)?(:<portNum>)? 1
roxctl netpol generate -h
roxctl netpol generate <folder_path> [flags] 1
roxctl netpol connectivity map <folder_path> [flags] 1
dot -Tsvg connlist_output.dot > connlist_output_graph.svg
roxctl netpol connectivity diff --dir1= <folder_path_1> --dir2= <folder_path_2> [flags] 1
apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: creationTimestamp: null name: backend-netpol spec: ingress: - from: - podSelector: matchLabels: app: frontend ports: - port: 9090 protocol: TCP podSelector: matchLabels: app: backendservice policyTypes: - Ingress - Egress status: {}
diff netpol-diff-example-minimal/netpols.yaml netpol-analysis-example-minimal/netpols.yaml
12c12 < - ports: --- > ports:
roxctl netpol connectivity diff --dir1=roxctl/netpol/connectivity/diff/testdata/netpol-analysis-example-minimal/ --dir2=roxctl/netpol/connectivity/diff/testdata/netpol-diff-example-minimal
Connectivity diff: diff-type: changed, source: default/frontend[Deployment], destination: default/backend[Deployment], dir1: TCP 9090, dir2: TCP 9090,UDP 53 diff-type: added, source: 0.0.0.0-255.255.255.255, destination: default/backend[Deployment], dir1: No Connections, dir2: TCP 9090