TELCODOCS-2309-plugin

installing/install_config/configuring-firewall.adoc

@@ -1,6 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="configuring-firewall"]
 = Configuring your firewall
+
 include::_attributes/common-attributes.adoc[]
 :context: configuring-firewall
 
@@ -16,3 +17,16 @@ include::modules/configuring-firewall.adoc[leveloffset=+1]
 * xref:../../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-auth-flow-aws-oidc_cco-short-term-creds[OpenID Connect requirements for AWS STS]
 
 include::modules/network-flow-matrix.adoc[leveloffset=+1]
+
+include::modules/network-commatrix-plugin-intro.adoc[leveloffset=+1]
+
+include::modules/network-commatrix-plugin-install.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../cli_reference/cli_manager/index.adoc#cli-manager-overview[{cli-manager} overview]
+
+include::modules/network-commatrix-plugin-generate.adoc[leveloffset=+1]
+
+include::modules/commatrix-plugin-reference.adoc[leveloffset=+1]

modules/commatrix-plugin-reference.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-firewall.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="commatrix-plugin-reference_{context}"]
+= Reference flags for the `commatrix` plugin
+
+The following matrix describes the flags for the `commatrix` plugin.
+
+[cols="2,1,3", options="header"]
+|===
+|Flag |Type |Description
+
+|`--customEntriesFormat` |string |Define the format of a custom entries file. The plugin appends the entries in this file to the generated data. Supported values are `json`, `yaml`, or `csv`.
+
+|`--customEntriesPath` |string |Define the file path to a custom entries file. The plugin appends the entries in this file to the generated data.
+
+|`--debug` |boolean |Enable verbose logging for debugging. The default value is `false`.
+
+|`--destDir` |string |Define the directory for output files. The default value is `communication-matrix`.
+
+|`--format` |string |Define the output format. Supported values are `json`, `yaml`, `csv`, or `nft`. The default value is `csv`.
+
+|`--host-open-ports` |boolean |Generate the expected communication data for the cluster environment. Identify the actual open ports on the cluster node to compare the difference between the expected open ports and the actual open ports. You can view the differences in the generated `matrix-diff-ss` file in the destination directory.
+
+|`-h` |boolean |Display the plugin help information.
+|===

modules/network-commatrix-plugin-generate.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-firewall.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="network-commatrix-plugin-generate_{context}"]
+= Generating ingress network flow data using the `commatrix` plugin
+
+Use the `commatrix` plugin for the `oc` command to generate ingress network flow data from your cluster and identify any differences between open ports on the host and expected ingress flows for your environment.
+
+.Prerequisites
+* You installed the OpenShift CLI (`oc`).
+* You logged in as a user with `cluster-admin` privileges.
+* You installed Podman.
+* You installed the `commatrix` plugin.
+
+.Procedure
+
+. Generate network flow data by running the following command:
++
+[source,bash]
+----
+$ oc commatrix generate
+----
++
+[NOTE]
+====
+By default, the plugin generates the network flow data in CSV format in a `communication-matrix` directory in your current working directory.
+====
+
+.Verification
+
+* View the generated network flow data in the `communication-matrix` directory by running the following command:
++
+[source,bash]
+----
+$ cat communication-matrix/communication-matrix.csv
+----
++
+[source,bash]
+----
+Direction,Protocol,Port,Namespace,Service,Pod,Container,Node Role,Optional
+Ingress,TCP,4194,kube-system,kubelet,konnectivity-agent,,,false
+Ingress,TCP,9100,openshift-monitoring,node-exporter,node-exporter,kube-rbac-proxy,,false
+Ingress,TCP,9103,openshift-ovn-kubernetes,ovn-kubernetes-node,ovnkube-node,kube-rbac-proxy-node,,false
+
+...
+----

modules/network-commatrix-plugin-install.adoc

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-firewall.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="network-commatrix-plugin-install_{context}"]
+= Installing the commatrix plugin
+
+[role="_abstract"]
+You can install the `commatrix` plugin from the Red Hat Ecosystem Catalog.
+
+[NOTE]
+====
+You can also install the `commatrix` plugin by using Krew. For more information, see "{cli-manager} overview".
+====
+
+.Prerequisites
+* You installed the OpenShift CLI (`oc`).
+* You installed Podman.
+
+.Procedure
+
+. Log in to the Red Hat Ecosystem Catalog registry by running the following command and entering your credentials:
++
+[source,bash]
+----
+$ podman login registry.redhat.io
+----
+
+. Extract the `commatrix` binary from the plugin image by running the following commands:
++
+[source,bash]
+----
+$ podman create --name oc-commatrix registry.redhat.io/openshift-kni/commatrix:v4.21
+$ podman cp oc-commatrix:/oc-commatrix .
+$ podman rm oc-commatrix
+----
+
+. Move the extracted binary to a directory in your system `PATH`, such as `/usr/local/bin/`, by running the following command:
++
+[source,bash]
+----
+sudo mv oc-commatrix /usr/local/bin/
+----
+
+
+.Verification
+
+* Run the following command to verify that the plugin is available locally:
++
+[source,bash]
+----
+$ oc commatrix
+----
++
+[source,bash]
+----
+Generate an up-to-date communication flows matrix for all ingress flows of openshift (multi-node and single-node in OpenShift) and Operators.
+
+ Optionally, generate a host open ports matrix and the difference with the communication matrix.
+
+ For additional details, please refer to the communication matrix documentation(https://github.com/openshift-kni/commatrix/blob/main/README.md).
+
+Usage:
+  commatrix [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  generate    Generate an up-to-date communication flows matrix for all ingress flows.
+  help        Help about any command
+
+Flags:
+  -h, --help   help for commatrix
+
+Use "commatrix [command] --help" for more information about a command.
+----

modules/network-commatrix-plugin-intro.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-firewall.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="network-commatrix-plugin-intro_{context}"]
+= Ingress network flow analysis with the `commatrix` plugin
+
+The `commatrix` plugin for the `oc` command generates ingress network flow data from your cluster. You can also use the plugin to identify any differences between open ports on the host and expected ingress flows for your environment.
+
+The plugin generates ingress flows to {product-title} services for the following environments:
+
+* {product-title} on bare metal
+* {sno-caps} with other platforms
+* {product-title} on {aws-first}
+* {sno-caps} on {aws-short}
+
+The plugin outputs the network flow data in various formats, such as CSV or JSON.

modules/network-flow-matrix.adoc

@@ -13,6 +13,11 @@ The following network flow matrixes describe the ingress flows to {product-title
 * {product-title} on {aws-first}
 * {sno-caps} on {aws-short}
 
+[NOTE]
+====
+You can use the `commatrix` plugin for the `oc` command to generate local network flow data for your cluster. For more information see "Generating ingress network flow data using the `commatrix` plugin".
+====
+
 Use the information in the appropriate network flow matrix to help you manage ingress traffic for your specific environment. You can restrict ingress traffic to essential flows to improve network security.
 
 Additionally, consider the following dynamic port ranges when managing ingress traffic for both bare metal and cloud environments: