Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. 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.

Expand
Table 9.1. Network policy tools
CommandDescription

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.

9.1. Using the build-time network policy generator
Copy link

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.

9.1.1. Generating build-time network policies
Copy link

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

  1. 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.
  2. 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.

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

  4. Service network addresses must match the following official regular expression pattern: 

    (http(s)?://)?<svc>(.<ns>(.svc.cluster.local)?)?(:<portNum>)?
    1
    Copy to Clipboard Toggle word wrap
    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

  1. Verify that the build-time network policy generation feature is available by running the help command: 

    $ roxctl netpol generate -h
    Copy to Clipboard Toggle word wrap

  2. Generate the policies by using the netpol generate command: 

    $ roxctl netpol generate <folder_path> [flags]
    1
    Copy to Clipboard Toggle word wrap
    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.

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.

9.1.2. roxctl netpol generate command options
Copy link

The roxctl netpol generate command supports the following options:

Expand
OptionDescription

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

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.

Procedure

  • Run the following command to retrieve the connectivity mapping information: 

    $ roxctl netpol connectivity map <folder_path> [flags]
    1
    Copy to Clipboard Toggle word wrap
    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 9.1. Example output

    Expand
    srcdstconn

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

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.

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: 

    $ dot -Tsvg connlist_output.dot > connlist_output_graph.svg
    Copy to Clipboard Toggle word wrap

    The following are examples of the dot output and the resulting graph generated by Graphviz:

The roxctl netpol connectivity map command supports the following options:

Expand
OptionDescription

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

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.

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: 

    $ roxctl netpol connectivity diff --dir1=<folder_path_1> --dir2=<folder_path_2> [flags]
    1
    Copy to Clipboard Toggle word wrap
    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 9.2. Example output

    Expand
    diff-typesourcedestinationdir 1dir 2workloads-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:

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.

The roxctl netpol connectivity diff command supports the following options:

Expand
OptionDescription

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

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: {}
Copy to Clipboard Toggle word wrap

The change in dir2 is an added - before the ports attribute, which produces a difference output.

9.3.3.1. Syntactic difference output
Copy link

Procedure

  • Run the following command to compare the contents of the netpols.yaml files in the two specified directories: 

    $ diff netpol-diff-example-minimal/netpols.yaml netpol-analysis-example-minimal/netpols.yaml
    Copy to Clipboard Toggle word wrap

    Example output

    12c12
<   - ports:
---
>     ports:
    Copy to Clipboard Toggle word wrap

9.3.3.2. Semantic difference output
Copy link

Procedure

  • Run the following command to analyze the connectivity differences between the Kubernetes manifests and network policies in the two specified directories: 

    $ roxctl netpol connectivity diff --dir1=roxctl/netpol/connectivity/diff/testdata/netpol-analysis-example-minimal/ --dir2=roxctl/netpol/connectivity/diff/testdata/netpol-diff-example-minimal
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat