diff --git a/modules/cluster-compare-configure-inline-diff.adoc b/modules/cluster-compare-configure-inline-diff.adoc index 6a4660ebef..5a65f41e5a 100644 --- a/modules/cluster-compare-configure-inline-diff.adoc +++ b/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 `(?[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: "(?[a-z0-9]+)" bigTextBlock: |- This is a big text block with some static content, like this line. It also has a place where (?[a-z0-9]+) would put in their own name. (?[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: "(?[a-z0-9]+)" <1> bigTextBlock: |- This static content outside of a capture group should match exactly. Here is a username capture group: (?[a-z0-9]+). It should match this capture group: (?[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 (?…) matched multiple values: « mismatchuser | exampleuser » ---- \ No newline at end of file diff --git a/modules/cluster-compare-reference-args.adoc b/modules/cluster-compare-reference-args.adoc index c7c3bae1ef..b6808b6b8d 100644 --- a/modules/cluster-compare-reference-args.adoc +++ b/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. diff --git a/modules/cluster-compare-templating-reference.adoc b/modules/cluster-compare-templating-reference.adoc new file mode 100644 index 0000000000..0a9bdd4578 --- /dev/null +++ b/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 }} +---- + diff --git a/modules/using-cluster-compare-live-cluster.adoc b/modules/using-cluster-compare-live-cluster.adoc index efbea95f25..67007edaa3 100644 --- a/modules/using-cluster-compare-live-cluster.adoc +++ b/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 /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. +==== \ No newline at end of file diff --git a/modules/using-cluster-compare-must-gather.adoc b/modules/using-cluster-compare-must-gather.adoc index 226c9f818a..6d016cc0bf 100644 --- a/modules/using-cluster-compare-must-gather.adoc +++ b/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 /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. +==== \ No newline at end of file diff --git a/modules/using-cluster-compare-telco-ref.adoc b/modules/using-cluster-compare-telco-ref.adoc index 73453bbab6..f0c933fcff 100644 --- a/modules/using-cluster-compare-telco-ref.adoc +++ b/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. +==== \ No newline at end of file diff --git a/scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc b/scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc index e27917532b..05e81edd08 100644 --- a/scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc +++ b/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]