cmd

oc commatrix Plugin

Overview

The oc commatrix generate generates an up-to-date communication flows matrix for all ingress flows of OpenShift (multi-node and single-node deployments) and Operators.

For additional details, please refer to the commatrix documentation

Installation

Prerequisites

• OpenShift CLI (oc) installed and configured to access your cluster.
• Go installed for building the plugin, or download a pre-built binary (if available).

Install

This plugin can be installed with the Krew plugin manager:

oc krew install --manifest=commatrix-krew.yaml

Or build the code locally and install it in /usr/local/bin:

$ make build
$ sudo make install

You can now begin using this plugin as:

$ oc commatrix generate

Usage

Usage:
  oc commatrix generate [flags]

Flags:
      --customEntriesFormat string   Set the format of the custom entries file (json,yaml,csv)
      --customEntriesPath string     Add custom entries from a file to the matrix
      --debug                        Debug logs (default is false)
      --destDir string               Output files dir (default communication-matrix)
      --format string                Desired format (json,yaml,csv,nft,butane,mc) (default "csv")
      --host-open-ports              Generate communication matrix, host open port matrix, and their difference.
      --custom-node-group stringArray    Assign nodes matching a label selector to a custom group for separate firewall CRs (format: groupName=labelSelector). Repeatable.

Example Output

Once you run the oc commatrix generate command, the plugin will generate a communication matrix based on the ingress flows in your OpenShift cluster. The output will be saved to a file (destDir) in the chosen format, similar to the following. Note that Node Group resolves as:

• If --custom-node-group assigns the node to a custom group: that group name
• Else if MCP API available: pool name from node annotation machineconfiguration.openshift.io/currentConfig (e.g., master, worker, custom-ws)
• Else if hypershift.openshift.io/nodePool label is present: that label value
• Else: node role (e.g., master, worker)

csv example

$ oc commatrix generate --format csv
Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
Ingress,TCP,22,Host system service,sshd,,,master,true
Ingress,TCP,53,openshift-dns,dns-default,dns-default,dns,master,false
Ingress,TCP,80,openshift-ingress,router-internal-default,router-default,router,master,false
Ingress,TCP,111,Host system service,rpcbind,,,master,true

json example

$ oc commatrix generate --format json
[
    {
        "direction": "Ingress",
        "protocol": "TCP",
        "port": 22,
        "namespace": "Host system service",
        "service": "sshd",
        "pod": "",
        "container": "",
        "nodeGroup": "master",
        "optional": true
    },
    {
        "direction": "Ingress",
        "protocol": "TCP",
        "port": 53,
        "namespace": "openshift-dns",
        "service": "dns-default",
        "pod": "dns-default",
        "container": "dns",
        "nodeGroup": "master",
        "optional": false
    }
]

butane example

$ oc commatrix generate --format butane

The command generates per-pool Butane YAML configs and a node-disruption-policy.yaml patch file.

butane-master.yaml

variant: openshift
version: 4.17.0
metadata:
  name: 98-nftables-commatrix-master
  labels:
    machineconfiguration.openshift.io/role: master
systemd:
  units:
    - name: "nftables.service"
      enabled: true
      contents: |
        [Unit]
        Description=Netfilter Tables
        ...
storage:
  files:
    - path: /etc/sysconfig/nftables.conf
      mode: 0600
      overwrite: true
      contents:
        inline: |
          table inet openshift_filter
          delete table inet openshift_filter
          ...

mc example

$ oc commatrix generate --format mc

The command generates per-pool MachineConfig CRs (transpiled from Butane) and a node-disruption-policy.yaml patch file. To remove the firewall rules, simply delete the MachineConfig -- the MC controller will restart and reload the default nft rules.

node-disruption-policy.yaml

Both butane and mc formats produce this patch file. Apply it to avoid full node reboots when nftables rules are updated:

$ oc patch machineconfiguration cluster --type=merge --patch-file=node-disruption-policy.yaml

apiVersion: operator.openshift.io/v1
kind: MachineConfiguration
metadata:
  name: cluster
spec:
  nodeDisruptionPolicy:
    units:
      - name: nftables.service
        actions:
          - type: Reload
            reload:
              serviceName: nftables.service
    files:
      - path: /etc/sysconfig/nftables.conf
        actions:
          - type: Restart
            restart:
              serviceName: nftables.service

host-open-ports example command

$ oc commatrix generate --host-open-ports --format csv

the command will generate the follwing paths:

communication-matrix path

Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
Ingress,TCP,22,Host system service,sshd,,,master,true
Ingress,TCP,80,openshift-ingress,router-internal-default,router-default,router,master,false
Ingress,UDP,59975,,rpc.statd,,,master,false

ss-generated-matrix path

Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
Ingress,TCP,22,,sshd,,,master,false
Ingress,TCP,80,,haproxy,,router,master,false
Ingress,TCP,111,Host system service,rpcbind,,,master,true

matrix-diff-ss path

Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
Ingress,TCP,22,Host system service,sshd,,,master,true
Ingress,TCP,80,openshift-ingress,router-internal-default,router-default,router,master,false
- Ingress,TCP,111,Host system service,rpcbind,,,master,true
+ Ingress,UDP,59975,,rpc.statd,,,master,false

raw-ss-tcp path

node: clus0-0
LISTEN 0      4096    127.0.0.1:29103 0.0.0.0:* users:(("ovnkube",pid=10913,fd=8))
LISTEN 0      4096    127.0.0.1:29108 0.0.0.0:* users:(("ovnkube",pid=9764,fd=3))
LISTEN 0      4096    127.0.0.1:29105 0.0.0.0:* users:(("ovnkube",pid=10913,fd=7))

raw-ss-udp path

node: clus0-0
UNCONN 0      0      0.0.0.0:111   0.0.0.0:* users:(("rpcbind",pid=3919,fd=5),("systemd",pid=1,fd=169))
UNCONN 0      0      127.0.0.1:323   0.0.0.0:* users:(("chronyd",pid=2805,fd=5))
UNCONN 0      0      127.0.0.1:708   0.0.0.0:* users:(("rpc.statd",pid=3922,fd=8))

customEntriesFormat and customEntriesPath example command

$ oc commatrix generate --format csv --customEntriesFormat csv --customEntriesPath "communication-matrix/customEntriesPath"

contents of communication-matrix/customEntriesPath

Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
ingress,TCP,9050,example-namespace,example-service,example-pod,example-container,master,false
ingress,UDP,9051,example-namespace2,example-service2,example-pod2,example-container2,worker,false

The command will generate the communication matrix, including the custom entries. The output would look like this:

Direction,Protocol,Port,Namespace,Service,Pod,Container,NodeGroup,Optional
Ingress,TCP,22,Host system service,sshd,,,master,true
Ingress,TCP,53,openshift-dns,dns-default,dns-default,dns,master,false
ingress,TCP,9050,example-namespace,example-service,example-pod,example-container,master,false
ingress,UDP,9051,example-namespace2,example-service2,example-pod2,example-container2,worker,false

custom-node-group example

When a subset of worker nodes run additional services, use --custom-node-group to split them into a custom group with separate firewall rules. Nodes are selected using standard Kubernetes label selectors:

$ oc commatrix generate --format butane \
    --custom-node-group mc-ingress=node-role.kubernetes.io/ingress

This produces separate output per group:

• butane-master.yaml — master firewall rules
• butane-worker.yaml — standard worker firewall rules (workers without the ingress label)
• butane-mc-ingress.yaml — worker rules plus ports 80/443 for the ingress nodes

The flag is repeatable for multiple groups:

$ oc commatrix generate --format butane \
    --custom-node-group mc-ingress=node-role.kubernetes.io/ingress \
    --custom-node-group mc-storage=node-role.kubernetes.io/storage

Label selector syntax follows the standard Kubernetes conventions:

The --custom-node-group flag affects all output formats. In CSV/JSON/YAML, the nodeGroup field reflects the custom group name. In NFT/Butane/MC, a separate file is generated per group.

Important (Butane/MC formats): The generated Butane/MachineConfig CRs for custom groups can only be applied if the nodes are already placed in a matching MachineConfigPool. You must create the custom MCP first, then apply the generated CR. For NFT/CSV/JSON/YAML formats, the output can be used directly without this prerequisite.