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 you use either the `regex` or `capturegroups` function for inline validation, the `cluster-compare` plugin enforces that identically named capture groups have 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 be 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 have 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,8 +96,16 @@ kind: ConfigMap
 metadata:
   namespace: dashboard
 data:
+  username: "(?<username>[a-z0-9]+)" <1>
   bigTextBlock: |-
     This static content outside of a capture group should match exactly.
     Here is a username capture group: (?<username>[a-z0-9]+). 
     It should match this capture group: (?<username>[a-z0-9]+).
+----
+<1> If the username value in the `data.username` field and the value captured in `bigTextBlock` do not match, the `cluster-compare` plugin warns you about the inconsistent matching. 
++
+.Example output with warning about the inconsistent matching:
+[source,terminal]
+----
+WARNING: Capturegroup (?<username>…) matched multiple values: « mismatchuser | exampleuser »
 ----

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,115 @@
+// 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. For the full list of `sprig` library functions, see "Sprig Function Documentation".
+
+The following table describes the additional template functions for the `cluster-compare` plugin:
+
+.Additional cluster-compare template functions
+[cols=".^2,.^4,.^6a",options="header"]
+|====
+
+|Function |Description |Example
+
+|`fromJson`
+|Parses the incoming string as a structured JSON object.
+|`value: {{ obj := spec.jsontext \| fromJson }}{{ obj.field }}`
+
+|`fromJsonArray`
+|Parses the incoming string as a structured JSON array.
+| `value: {{ obj := spec.jsontext \| fromJson}}{{ index $obj 0 }}`
+
+|`fromYaml`
+|Parses the incoming string as a structured YAML object.
+|`value: {{ obj := spec.yamltext \| fromYaml }}{{ obj.field }}`
+
+|`fromYamlArray`
+|Parses the incoming string as a structured YAML array.
+|`value: {{ obj := spec.yamltext \| fromYaml}}{{ index $obj 0 }`
+
+|`toJson`
+|Renders incoming data as JSON while preserving object types.
+|`jsonstring: {{ $variable \| toJson }}`
+
+|`toToml`
+|Renders the incoming string as structured TOML data.
+|`tomlstring: {{ $variable \| toToml }}`
+
+|`toYaml`
+|Renders incoming data as YAML while preserving object types.
+|For simple scalar values: `value: {{ $data \| toYaml }}`
+
+For lists or dictionaries: `value: {{ $dict \| toYaml \| nindent 2 }}`
+
+|`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 excluded due to `doNotMatch` are not considered comparison failures.
+
+This function is especially useful when your template does not specify a fixed name or namespace. In these cases, you can use the `doNotMatch` function to exclude specific resources based on other fields, such as `labels` or `annotations`.
+|`{{ if $condition }}{{ doNotMatch $reason }}{{ end }}`
+
+|`lookupCRs`
+|Returns an array of objects that match the specified parameters. For example: `lookupCRs $apiVersion $kind $namespace $name`.
+
+If the `$namespace` parameter is an empty string (`""`) or `\*`, the function matches all namespaces. For cluster-scoped objects, the function matches objects with no namespace.
+
+If the `$name` is an empty string or `*`, the function matches any named object.
+|-
+
+|`lookupCR`
+|Returns a single object that matches the parameters. If multiple objects match, the function returns nothing. This function takes the same arguments as the `lookupCRs` function.
+|-
+
+|====
+
+The following example shows how to use the `lookupCRs` function to retrieve and render values from multiple matching resources:
+
+.Config map example using `lookupCRs`
+[source,yaml]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  labels:
+    k8s-app: kubernetes-dashboard
+  name: kubernetes-dashboard-settings
+  namespace: kubernetes-dashboard
+data:
+  dashboard: {{ index (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "kubernetes-dashboard") "metadata" "name" \| toYaml }}
+  metrics: {{ (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "dashboard-metrics-scraper").metadata.name \| toYaml }}
+----
+
+The following example shows how to use the `lookupCR` function to retrieve and use specific values from a single matching resource:
+
+.Config map example using `lookupCR`
+[source,yaml]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  labels:
+    k8s-app: kubernetes-dashboard
+  name: kubernetes-dashboard-settings
+  namespace: kubernetes-dashboard
+data:
+  {{- $objlist := lookupCRs "apps/v1" "Deployment" "kubernetes-dashboard" "*" }}
+  {{- $dashboardName := "unknown" }}
+  {{- $metricsName := "unknown" }}
+  {{- range $obj := $objlist }}
+    {{- $appname := index $obj "metadata" "labels" "k8s-app" }}
+    {{- if contains "metrics" $appname }}
+      {{- $metricsName = $obj.metadata.name }}
+    {{- end }}
+    {{- if eq "kubernetes-dashboard" $appname }}
+      {{- $dashboardName = $obj.metadata.name }}
+    {{- end }}
+  {{- end }}
+  dashboard: {{ $dashboardName }}
+  metrics: {{ $metricsName }}
+----
+

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

@@ -84,3 +84,18 @@ 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]
+====
+Get the output in the `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
+----
+
+The `junit` output includes the following result types:
+
+* Passed results for each fully matched template.
+* Failed results for differences found or missing required custom resources (CRs).
+* Skipped results for differences patched using the user override mechanism.
+====

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

@@ -82,3 +82,18 @@ 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]
+====
+Get the output in the `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
+----
+
+The `junit` output includes the following result types:
+
+* Passed results for each fully matched template.
+* Failed results for differences found or missing required custom resources (CRs).
+* Skipped results for differences patched using the user override mechanism.
+====

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

@@ -158,3 +158,18 @@ 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]
+====
+Get the output in the `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
+----
+
+The `junit` output includes the following result types:
+
+* Passed results for each fully matched template.
+* Failed results for differences found or missing required custom resources (CRs).
+* Skipped results for differences patched using the user override mechanism.
+====

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]