OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

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

Using the build-time network policy generator

Build-time network policy generation is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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.

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

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

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

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

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.

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.

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.

Connectivity mapping using the roxctl netpol connectivity map command

Build-time network policy connectivity mapping is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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.

Retrieving connectivity mapping information from a Kubernetes manifest directory

Procedure

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

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

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.

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

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.

Identifying the differences in allowed connections between project versions

Build-time network policy connectivity difference is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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, and csv.

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:

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

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

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.

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

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.

Syntactic difference output

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
    Example output
    12c12
<   - ports:
---
>     ports:

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:

    $ 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