commatrix

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
nodePool       Resolved MachineConfigPool name (e.g., master, worker, or custom pool)
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>.

The resolved pool name is recorded in the nodePool field of each matrix entry, and NFT output is generated per pool.