commatrix

This project allows to automatically generate an accurate and up-to-date communication
flows matrix that can be delivered to customers as part of product documentation for all
ingress flows of OpenShift (multi-node and single-node deployments).

Usage of the EndpointSlice Resource

This library leverages the EndpointSlice resource to identify the ports the
cluster uses for ingress traffic. Relevant EndpointSlices include those
referencing host-networked pods, Node Port services, and LoadBalancer services.

Creating Custom ComDetails with ss Command

The ss command, a Linux utility, lists open ports on
the host with ss -anplt for TCP or ss -anplu for UDP. For example, consider the following ss entry:

LISTEN 0      4096    127.0.0.1:10248 0.0.0.0:* users:(("kubelet",pid=6187,fd=20))

The ss package provides the CreateSSOutputFromNode function that runs the ss command on each node, and converts the output into a corresponding ComDetails list.

Communication Matrix Creation Guide

Use the generate Makefile target to create the matrix. Add additional entires to the matrix via a custom file, using the variables CUSTOM_ENTRIES_PATH and CUSTOM_ENTRIES_FORMAT. Examples are available in the example-custom-entries files.

The following environment variables are used to configure:

FORMAT (csv/json/yaml/nft)
DEST_DIR (path to the directory containing the artifacts)
CUSTOM_ENTRIES_PATH (path to the file containing custom entries to add to the matrix)
CUSTOM_ENTRIES_FORMAT (the format of the custom entries file (json,yaml,csv))

The generated artifcats are:

communication-matrix - The generated communication matrix.
ss-generated-matrix - The communication matrix that generated by the `ss` command.
matrix-diff-ss - Shows the variance between two matrices. Entries present in the communication matrix but absent in the ss matrix are marked with '+', while entries present in the ss matrix but not in the communication matrix are marked with '-'.
raw-ss-tcp - The raw `ss` output for TCP.
raw-ss-udp - The raw `ss` output for UDP.

Each record describes a flow with the following information:

direction      Data flow direction (currently ingress only)
protocol       IP protocol (TCP/UDP/SCTP/etc)
port           Flow port number
namespace      EndpointSlice Namespace
service        EndpointSlice owner Service name
pod            EndpointSlice target Pod name
container      Port owner Container name
nodeGroup      Resolved node group. Resolution logic:
               - If MCP API available: nodeGroup = pool name parsed from node annotation
                 machineconfiguration.openshift.io/currentConfig (e.g., master, worker, custom-ws)
               - Else if label hypershift.openshift.io/nodePool present: nodeGroup = that label value
               - Else: nodeGroup = node role (e.g., master, worker)
optional       Optional or mandatory flow for OpenShift

MachineConfigPool selection

When associating a node to a MachineConfigPool (MCP), the pool is derived directly from the node annotation machineconfiguration.openshift.io/currentConfig, expected in the form rendered-<pool>-<hash>. The pool name is obtained by removing the rendered- prefix and trimming the trailing -<hash>.

If MCPs are not present in the cluster (e.g., HyperShift), nodeGroup is computed as:

1. use hypershift.openshift.io/nodePool label when available.
2. otherwise fall back to the node role.

The resolved group is recorded in the nodeGroup field for CSV/JSON/YAML outputs. NFT output is generated per node pool (MCP) or node role accordingly.