Merge pull request #85563 from rohennes/TELCODOCS-1891

Author: adellape

_topic_maps/_topic_map.yml

@@ -3279,6 +3279,22 @@ Topics:
       File: telco-core-ref-crs
     - Name: Telco core software specifications
       File: telco-core-ref-software-artifacts
+- Name: Comparing cluster configurations
+  Dir: cluster-compare
+  Distros: openshift-origin,openshift-enterprise
+  Topics:
+  - Name: Understanding the cluster-compare plugin
+    File: understanding-the-cluster-compare-plugin
+  - Name: Installing the cluster-compare plugin
+    File: installing-cluster-compare-plugin
+  - Name: Using the cluster-compare plugin
+    File: using-the-cluster-compare-plugin
+  - Name: Creating a reference configuration
+    File: creating-a-reference-configuration
+  - Name: Performing advanced reference configuration customization
+    File: advanced-ref-config-customization
+  - Name: Troubleshooting cluster comparisons
+    File: troubleshooting-cluster-comparisons
 - Name: Planning your environment according to object maximums
   File: planning-your-environment-according-to-object-maximums
   Distros: openshift-origin,openshift-enterprise

images/493-OpenShift-0125.png

@@ -0,0 +1,96 @@
+// Module included in the following assembly:
+//
+// * scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="cluster-compare-configure-inline-diff_{context}"]
+= Configuring inline validation for template fields
+
+You can enable inline regular expressions to validate template fields, especially in scenarios where Golang templating syntax is difficult to maintain or overly complex. Using inline regular expressions simplifies templates, improves readability, and allows for more advanced validation logic.
+
+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.
+
+[id="cluster-compare-configure-regex_{context}"]
+== Configuring inline validation with the regex function
+
+Use the `regex` inline function to validate fields using regular expressions.
+
+.Procedure
+
+. Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+[source,yaml]
+----
+apiVersion: v2
+parts:
+- name: Part1
+  components:
+  - name: Example
+    allOf:
+    - path: example.yaml
+      config:
+        perField:
+        - pathToKey: spec.bigTextBlock <1>
+          inlineDiffFunc: regex <2>
+----
+<1> Specifies the field for inline validation.
+<2> Enables inline validation using regular expressions.
+
+. Use a regular expression to validate the field in the associated template:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  namespace: dashboard
+data:
+  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.
+----
+
+[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. 
+
+.Procedure
+
+. Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+[source,yaml]
+----
+apiVersion: v2
+parts:
+- name: Part1
+  components:
+  - name: Example
+    allOf:
+    - path: example.yaml
+      config:
+        perField:
+        - pathToKey: spec.bigTextBlock <1>
+          inlineDiffFunc: capturegroups <2>
+----
+<1> Specifies the field for inline validation.
+<2> Enables inline validation using capture groups.
+
+. Use a regular expression to validate the field in the associated template:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  namespace: dashboard
+data:
+  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]+).
+----

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

@@ -0,0 +1,142 @@
+// Module included in the following assembly:
+//
+// * scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="cluster-compare-exclude-metadata_{context}"]
+= Configuring the metadata.yaml file to exclude template fields
+
+You can configure the `metadata.yaml` file to exclude fields from a comparison. Exclude fields that are irrelevant to a comparison, for example annotations or labels that are inconsequential to a cluster configuration. 
+
+You can configure exclusions in the `metadata.yaml` file in the following ways:
+
+* Exclude all fields in a custom resource not specified in a template.
+
+* Exclude specific fields that you define using the `pathToKey` field.
++
+[NOTE]
+====
+`pathToKey` is a dot separated path. Use quotes to escape key values featuring a period.
+====
+
+[id="cluster-compare-ignore-all-fields_{context}"]
+== Excluding all fields not specified in a template
+
+During the comparison process, the `cluster-compare` plugin renders a template by merging fields from the corresponding custom resource (CR). If you configure the `ignore-unspecified-fields` to `true`, all fields that are present in the CR, but not in the template, are excluded from the merge. Use this approach when you want to focus the comparison on the fields specified in the template only.
+
+.Procedure
+
+* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+[source,yaml]
+----
+apiVersion: v2
+parts:
+  - name: Part1
+    components:
+      - name: Namespace
+        allOf:
+          - path: namespace.yaml
+            config:
+              ignore-unspecified-fields: true <1>
+#...
+----
+<1> Specify `true` to exclude from the comparison all fields in a CR that are not explicitly configured in the corresponding `namespace.yaml` template.
+
+[id="cluster-compare-ignore-default-fields_{context}"]
+== Excluding specific fields by setting default exclusion fields
+
+You can exclude fields by defining a default value for `fieldsToOmitRefs` in the `defaultOmitRef` field. This default exclusion applies to all templates, unless overridden by the `config.fieldsToOmitRefs` field for a specific template.
+
+.Procedure
+
+* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+.Example metadata.yaml file
+[source,yaml]
+----
+apiVersion: v2
+parts:
+
+#...
+
+fieldsToOmit:
+   defaultOmitRef: default <1>
+   items:
+      default:
+         - pathToKey: a.custom.default."k8s.io" <2>
+----
+<1> Sets the default exclusion for all templates, unless overridden by the `config.fieldsToOmitRefs` field for a specific template.
+<2> The value is excluded for all templates.
+
+[id="cluster-compare-ignore-specified-fields_{context}"]
+== Excluding specific fields
+
+You can specify fields to exclude by defining the path to the field, and then referencing the definition in the `config` section for a template. 
+
+.Procedure
+
+* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+.Example metadata.yaml file
+[source,yaml]
+----
+apiVersion: v2
+parts:
+  - name: Part1
+    components:
+      - name: Component1
+        - path: deployment.yaml
+          config:
+            fieldsToOmitRefs:
+              - deployments <1>
+
+#...
+
+fieldsToOmit:
+   items:
+      deployments:
+         - pathToKey: spec.selector.matchLabels.k8s-app <2>
+----
+<1> References the `fieldsToOmit.items.deployments` item for the `deployment.yaml` template.
+<2> Excludes the `spec.selector.matchLabels.k8s-app` field from the comparison. 
++
+[NOTE]
+====
+Setting `fieldsToOmitRefs` replaces the default value.
+====
+
+[id="cluster-compare-ignore-default-groups_{context}"]
+== Excluding specific fields by setting default exclusion groups
+
+You can create default groups of fields to exclude. A group of exclusions can reference another group to avoid duplication when defining exclusions. 
+
+.Procedure
+
+* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+.Example metadata.yaml file
+[source,yaml]
+----
+apiVersion: v2
+parts:
+
+#...
+
+fieldsToOmit:
+   defaultOmitRef: default
+   items:
+    common:
+      - pathToKey: metadata.annotations."kubernetes.io/metadata.name"
+      - pathToKey: metadata.annotations."kubernetes.io/metadata.name"
+      - pathToKey: metadata.annotations."kubectl.kubernetes.io/last-applied-configuration"
+      - pathToKey: metadata.creationTimestamp
+      - pathToKey: metadata.generation
+      - pathToKey: spec.ownerReferences
+      - pathToKey: metadata.ownerReferences
+    default:
+      - include: common <1>
+      - pathToKey: status
+----
+<1> The `common` group is included in the default group.

modules/cluster-compare-exclude-metadata.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assembly:
+//
+// * scalability_and_performance/cluster-compare/advanced-ref-config-customization.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="cluster-compare-manual-match_{context}"]
+= Configuring manual matching between CRs and templates
+
+For scenarios where the `cluster-compare` plugin's default matching does not work as expected, you can manually match a custom resource (CR) to a template. 
+
+For example, if there is more than one CR in the cluster with the same `apiversion`, `kind`, `name`, and `namespace` fields, the plugin's default matching compares the CR that features the least differences. To control what CR the plugin chooses, you can create a user configuration YAML file with the manual matching configuration, then pass this configuration file to the `cluster-compare` command.
+
+.Procedure
+
+. Create a user configuration file to define the manual matching criteria:
++
+.Example `user-config.yaml` file
+[source,yaml]
+----
+correlationSettings:
+   manualCorrelation:
+      correlationPairs:
+         apps.v1.DaemonSet.kube-system.kindnet.yaml: "template_example.yaml" <1>
+----
+<1> Specifies the CR and template pair to match. The CR specification uses the following format: `<apiversion>.<kind>.<namespace>.<name>`. For cluster scoped CRs that do not have a namespace, use the format `<apiversion>.<kind>.<name>`.
+
+. Reference the user configuration file in a `cluster-compare` command by running the following command:
++
+[source,terminal]
+----
+$ oc cluster-compare -r <path_to_reference_config>/metadata.yaml -c <path_to_user_config>/user-config.yaml <1>
+----
+<1> Specify the `user-config.yaml` file by using the `-c` option.

modules/cluster-compare-manual-match.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+
+// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="cluster-compare-metadata-structure_{context}"]
+= Structure of the metadata.yaml file
+
+The `metadata.yaml` file provides a central configuration point to define and configure the templates in a reference configuration. 
+The file features a hierarchy of `parts` and `components`. `parts` are groups of `components` and `components` are groups of templates.
+Under each component, you can configure template dependencies, validation rules, and add descriptive metadata.
+
+.Example metadata.yaml file
+[source,yaml]
+----
+apiVersion: v2
+parts: <1>
+  - name: Part1 <2>
+    components:
+      - name: Component1 <3>
+        <component1_configuration> <4>
+  - name: Part2
+      - name: Component2
+        <component2_configuration>
+----
+<1> Every `part` typically describes a workload or a set of workloads.
+<2> Specify a `part` name.
+<3> Specify a `component` name.
+<4> Specify the configuration for a template. For example, define template relationships or configure what fields to use in a comparison.

modules/cluster-compare-metadata-structure.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+
+// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="cluster-compare-output-description_{context}"]
+= Configuring descriptions for the output
+
+Each part, component, or template can include descriptions to provide additional context, instructions, or documentation links. These descriptions are helpful to convey why a specific template or structure is required.
+
+.Procedure
+
+* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
++
+[source,yaml]
+----
+apiVersion: v2
+parts:
+  - name: Part1
+    description: |-
+      General text for every template under this part, unless overridden.
+    components:
+      - name: Component1
+        # With no description set, this inherits the description from the part above.
+        OneOf:
+          - path: Template1.yaml
+            # This inherits the component description, if set.
+          - path: Template2.yaml
+          - path: Template3.yaml
+            description: |-
+              This template has special instructions that don't apply to the others.
+      - name: Component2
+        description: |-
+          This overrides the part text with something more specific.
+          Multi-line text is supported, at all levels.
+        allOf:
+          - path: RequiredTemplate1.yaml
+          - path: RequiredTemplate2.yaml
+            description: |-
+              Required for important reasons.
+          - path: RequiredTemplate3.yaml
+----