TELCODOCS#2148: Usability improvements in cluster-compare plugin

Author: sr1kar99

modules/cluster-compare-configure-inline-diff.adoc

@@ -14,6 +14,8 @@ The `cluster-compare` plugin provides two functions for inline validation:
 * `regex`: Validates content in a field using a regular expression.
 * `capturegroups`: Enhances multi-line text comparisons by processing non-capture group text as exact matches, applying regular expression matching only within named capture groups, and ensuring consistency for repeated capture groups.
 
+When using the `regex` or `capturegroups` function for inline validation, the `cluster-compare` plugin enforces that identically named capture groups match the same values across multiple fields within a template. This means that if a named capture group, such as `(?<username>[a-z0-9]+)`, appears in multiple fields, the values for that group must remain consistent throughout the template.
+
 [id="cluster-compare-configure-regex_{context}"]
 == Configuring inline validation with the regex function
 
@@ -49,6 +51,7 @@ kind: ConfigMap
 metadata:
   namespace: dashboard
 data:
+  username: "(?<username>[a-z0-9]+)"
   bigTextBlock: |-
     This is a big text block with some static content, like this line.
     It also has a place where (?<username>[a-z0-9]+) would put in their own name. (?<username>[a-z0-9]+) would put in their own name.
@@ -57,7 +60,7 @@ data:
 [id="cluster-compare-configure-capturegroups_{context}"]
 == Configuring inline validation with the capturegroups function
 
-Use the `capturegroups` inline function for more precise validation of fields featuring multi-line strings. 
+Use the `capturegroups` inline function for more precise validation of fields featuring multi-line strings. This function also ensures that identically named capture groups match the same values across multiple fields.
 
 .Procedure
 
@@ -74,11 +77,15 @@ parts:
     - path: example.yaml
       config:
         perField:
-        - pathToKey: spec.bigTextBlock <1>
-          inlineDiffFunc: capturegroups <2>
+        - pathToKey: data.username <1>
+          inlineDiffFunc: regex <2>
+        - pathToKey: spec.bigTextBlock <3>
+          inlineDiffFunc: capturegroups <4>
 ----
 <1> Specifies the field for inline validation.
 <2> Enables inline validation using capture groups.
+<3> Specifies the multi-line field for capture group validation.
+<4> Enables inline validation using capture groups.
 
 . Use a regular expression to validate the field in the associated template:
 +
@@ -89,6 +96,7 @@ kind: ConfigMap
 metadata:
   namespace: dashboard
 data:
+  username: "(?<username>[a-z0-9]+)"
   bigTextBlock: |-
     This static content outside of a capture group should match exactly.
     Here is a username capture group: (?<username>[a-z0-9]+). 

modules/cluster-compare-reference-args.adoc

@@ -29,6 +29,9 @@ The following content describes the options for the `cluster-compare` plugin.
 | `--generate-override-for` 
 | Specify the path for templates that requires a patch.
 
+| `--show-template-functions`
+| Displays the available template functions.
+
 [NOTE]
 ====
 You must use a file path for the target template that is relative to the `metadata.yaml` file. For example, if the file path for the `metadata.yaml` file is `./compare/metadata.yaml`, a relative file path for the template might be `optional/my-template.yaml`.
@@ -41,7 +44,7 @@ You must use a file path for the target template that is relative to the `metada
 | Specify a path to process the `kustomization` directory. This flag cannot be used together with `-f` or `-R`.
 
 | `-o`, `--output` 
-| Specify the output format. Options include `json`, `yaml`, or `generate-patches`.
+| Specify the output format. Options include `json`, `yaml`, `junit`, or `generate-patches`.
 
 | `--override-reason` 
 | Specify a reason for generating the override.

modules/cluster-compare-templating-reference.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+
+// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
+
+:_mod-docs-content-type: REFERENCE
+
+[id="cluster-compare-templating-reference_{context}"]
+= Reference template functions
+
+The `cluster-compare` plugin supports all `sprig` library functions, except for the `env` and `expandenv` functions.
+See _Additional resources_ for the full list of `sprig` library functions.
+
+The following content describes the additional template functions for the `cluster-compare` plugin. 
+
+.Additional cluster-compare template functions
+[options="header"]
+[cols="2a,3a"]
+|====
+| Function | Description
+
+|`fromJson`
+|Parses the incoming string as a structured JSON object.
+
+|`fromJsonArray`
+|Parses the incoming string as a structured JSON array.
+
+|`fromYaml`
+|Parses the incoming string as a structured YAML object.
+
+|`fromYamlArray`
+|Parses the incoming string as a structured YAML array.
+
+|`toJson`
+|Renders incoming data as JSON while preserving object types.
+
+|`toToml`
+|Renders the incoming string as structured TOML data.
+
+|`toYaml`
+|Renders incoming data as YAML while preserving object types.
+
+|`doNotMatch`
+|Prevents a template from matching a cluster resource, even if it would normally match. You can use this function inside a template to conditionally exclude certain resources from correlation. The specified reason is logged when running with the `--verbose` flag. Templates skipped solely due to `doNotMatch` are not considered comparison failures.
+
+|====

modules/using-cluster-compare-live-cluster.adoc

@@ -84,3 +84,12 @@ No patched CRs <10>
 <8> The CRs that did not match to a corresponding template in the reference configuration.
 <9> The metadata hash identifies the reference configuration.
 <10> The list of patched CRs.
+
+[NOTE]
+====
+You can also get the output in `junit` format by adding `-o junit` to the command. For example:
+[source,terminal]
+----
+$ oc cluster-compare -r <path_to_reference_config>/metadata.yaml -o junit
+----
+====

modules/using-cluster-compare-must-gather.adoc

@@ -82,3 +82,12 @@ No patched CRs <10>
 <8> The CRs that did not match to a corresponding template in the reference configuration.
 <9> The metadata hash identifies the reference configuration.
 <10> The list of patched CRs.
+
+[NOTE]
+====
+You can also get the output in `junit` format by adding `-o junit` to the command. For example:
+[source,terminal]
+----
+$ oc cluster-compare -r <path_to_reference_config>/metadata.yaml -f "must-gather*/*/cluster-scoped-resources","must-gather*/*/namespaces" -R -o junit
+----
+====

modules/using-cluster-compare-telco-ref.adoc

@@ -158,3 +158,12 @@ No patched CRs <10>
 <8> The CRs that did not match to a corresponding template in the reference configuration.
 <9> The metadata hash identifies the reference configuration.
 <10> The list of patched CRs.
+
+[NOTE]
+====
+You can also get the output in `junit` format by adding `-o junit` to the command. For example:
+[source,terminal]
+----
+$ oc cluster-compare -r out/telco-core-rds/configuration/reference-crs-kube-compare/metadata.yaml -o junit
+----
+====

scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc

@@ -14,6 +14,13 @@ include::modules/cluster-compare-template-groupings.adoc[leveloffset=+1]
 
 include::modules/cluster-compare-templating.adoc[leveloffset=+1]
 
+include::modules/cluster-compare-templating-reference.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://masterminds.github.io/sprig/[Sprig Function Documentation]
+
 include::modules/cluster-compare-exclude-metadata.adoc[leveloffset=+1]
 
 include::modules/cluster-compare-configure-inline-diff.adoc[leveloffset=+1]