Skip to content

Commit 8c5f733

Browse files
adellapeadellape
authored
Merge pull request #85563 from rohennes/TELCODOCS-1891
2 parents bb46a22 + de1619d commit 8c5f733

30 files changed

+1512
-1
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3279,6 +3279,22 @@ Topics:
32793279
File: telco-core-ref-crs
32803280
- Name: Telco core software specifications
32813281
File: telco-core-ref-software-artifacts
3282+
- Name: Comparing cluster configurations
3283+
Dir: cluster-compare
3284+
Distros: openshift-origin,openshift-enterprise
3285+
Topics:
3286+
- Name: Understanding the cluster-compare plugin
3287+
File: understanding-the-cluster-compare-plugin
3288+
- Name: Installing the cluster-compare plugin
3289+
File: installing-cluster-compare-plugin
3290+
- Name: Using the cluster-compare plugin
3291+
File: using-the-cluster-compare-plugin
3292+
- Name: Creating a reference configuration
3293+
File: creating-a-reference-configuration
3294+
- Name: Performing advanced reference configuration customization
3295+
File: advanced-ref-config-customization
3296+
- Name: Troubleshooting cluster comparisons
3297+
File: troubleshooting-cluster-comparisons
32823298
- Name: Planning your environment according to object maximums
32833299
File: planning-your-environment-according-to-object-maximums
32843300
Distros: openshift-origin,openshift-enterprise

‎images/493-OpenShift-0125.png

77 KB
Loading

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

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
// Module included in the following assembly:
2+
//
3+
// * scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="cluster-compare-configure-inline-diff_{context}"]
8+
= Configuring inline validation for template fields
9+
10+
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.
11+
12+
The `cluster-compare` plugin provides two functions for inline validation:
13+
14+
* `regex`: Validates content in a field using a regular expression.
15+
* `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.
16+
17+
[id="cluster-compare-configure-regex_{context}"]
18+
== Configuring inline validation with the regex function
19+
20+
Use the `regex` inline function to validate fields using regular expressions.
21+
22+
.Procedure
23+
24+
. Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
25+
+
26+
[source,yaml]
27+
----
28+
apiVersion: v2
29+
parts:
30+
- name: Part1
31+
components:
32+
- name: Example
33+
allOf:
34+
- path: example.yaml
35+
config:
36+
perField:
37+
- pathToKey: spec.bigTextBlock <1>
38+
inlineDiffFunc: regex <2>
39+
----
40+
<1> Specifies the field for inline validation.
41+
<2> Enables inline validation using regular expressions.
42+
43+
. Use a regular expression to validate the field in the associated template:
44+
+
45+
[source,yaml]
46+
----
47+
apiVersion: v1
48+
kind: ConfigMap
49+
metadata:
50+
namespace: dashboard
51+
data:
52+
bigTextBlock: |-
53+
This is a big text block with some static content, like this line.
54+
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.
55+
----
56+
57+
[id="cluster-compare-configure-capturegroups_{context}"]
58+
== Configuring inline validation with the capturegroups function
59+
60+
Use the `capturegroups` inline function for more precise validation of fields featuring multi-line strings.
61+
62+
.Procedure
63+
64+
. Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
65+
+
66+
[source,yaml]
67+
----
68+
apiVersion: v2
69+
parts:
70+
- name: Part1
71+
components:
72+
- name: Example
73+
allOf:
74+
- path: example.yaml
75+
config:
76+
perField:
77+
- pathToKey: spec.bigTextBlock <1>
78+
inlineDiffFunc: capturegroups <2>
79+
----
80+
<1> Specifies the field for inline validation.
81+
<2> Enables inline validation using capture groups.
82+
83+
. Use a regular expression to validate the field in the associated template:
84+
+
85+
[source,yaml]
86+
----
87+
apiVersion: v1
88+
kind: ConfigMap
89+
metadata:
90+
namespace: dashboard
91+
data:
92+
bigTextBlock: |-
93+
This static content outside of a capture group should match exactly.
94+
Here is a username capture group: (?<username>[a-z0-9]+).
95+
It should match this capture group: (?<username>[a-z0-9]+).
96+
----

‎modules/cluster-compare-exclude-metadata.adoc

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
// Module included in the following assembly:
2+
//
3+
// * scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="cluster-compare-exclude-metadata_{context}"]
8+
= Configuring the metadata.yaml file to exclude template fields
9+
10+
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.
11+
12+
You can configure exclusions in the `metadata.yaml` file in the following ways:
13+
14+
* Exclude all fields in a custom resource not specified in a template.
15+
16+
* Exclude specific fields that you define using the `pathToKey` field.
17+
+
18+
[NOTE]
19+
====
20+
`pathToKey` is a dot separated path. Use quotes to escape key values featuring a period.
21+
====
22+
23+
[id="cluster-compare-ignore-all-fields_{context}"]
24+
== Excluding all fields not specified in a template
25+
26+
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.
27+
28+
.Procedure
29+
30+
* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
31+
+
32+
[source,yaml]
33+
----
34+
apiVersion: v2
35+
parts:
36+
- name: Part1
37+
components:
38+
- name: Namespace
39+
allOf:
40+
- path: namespace.yaml
41+
config:
42+
ignore-unspecified-fields: true <1>
43+
#...
44+
----
45+
<1> Specify `true` to exclude from the comparison all fields in a CR that are not explicitly configured in the corresponding `namespace.yaml` template.
46+
47+
[id="cluster-compare-ignore-default-fields_{context}"]
48+
== Excluding specific fields by setting default exclusion fields
49+
50+
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.
51+
52+
.Procedure
53+
54+
* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
55+
+
56+
.Example metadata.yaml file
57+
[source,yaml]
58+
----
59+
apiVersion: v2
60+
parts:
61+
62+
#...
63+
64+
fieldsToOmit:
65+
defaultOmitRef: default <1>
66+
items:
67+
default:
68+
- pathToKey: a.custom.default."k8s.io" <2>
69+
----
70+
<1> Sets the default exclusion for all templates, unless overridden by the `config.fieldsToOmitRefs` field for a specific template.
71+
<2> The value is excluded for all templates.
72+
73+
[id="cluster-compare-ignore-specified-fields_{context}"]
74+
== Excluding specific fields
75+
76+
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.
77+
78+
.Procedure
79+
80+
* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
81+
+
82+
.Example metadata.yaml file
83+
[source,yaml]
84+
----
85+
apiVersion: v2
86+
parts:
87+
- name: Part1
88+
components:
89+
- name: Component1
90+
- path: deployment.yaml
91+
config:
92+
fieldsToOmitRefs:
93+
- deployments <1>
94+
95+
#...
96+
97+
fieldsToOmit:
98+
items:
99+
deployments:
100+
- pathToKey: spec.selector.matchLabels.k8s-app <2>
101+
----
102+
<1> References the `fieldsToOmit.items.deployments` item for the `deployment.yaml` template.
103+
<2> Excludes the `spec.selector.matchLabels.k8s-app` field from the comparison.
104+
+
105+
[NOTE]
106+
====
107+
Setting `fieldsToOmitRefs` replaces the default value.
108+
====
109+
110+
[id="cluster-compare-ignore-default-groups_{context}"]
111+
== Excluding specific fields by setting default exclusion groups
112+
113+
You can create default groups of fields to exclude. A group of exclusions can reference another group to avoid duplication when defining exclusions.
114+
115+
.Procedure
116+
117+
* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
118+
+
119+
.Example metadata.yaml file
120+
[source,yaml]
121+
----
122+
apiVersion: v2
123+
parts:
124+
125+
#...
126+
127+
fieldsToOmit:
128+
defaultOmitRef: default
129+
items:
130+
common:
131+
- pathToKey: metadata.annotations."kubernetes.io/metadata.name"
132+
- pathToKey: metadata.annotations."kubernetes.io/metadata.name"
133+
- pathToKey: metadata.annotations."kubectl.kubernetes.io/last-applied-configuration"
134+
- pathToKey: metadata.creationTimestamp
135+
- pathToKey: metadata.generation
136+
- pathToKey: spec.ownerReferences
137+
- pathToKey: metadata.ownerReferences
138+
default:
139+
- include: common <1>
140+
- pathToKey: status
141+
----
142+
<1> The `common` group is included in the default group.

‎modules/cluster-compare-manual-match.adoc

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Module included in the following assembly:
2+
//
3+
// * scalability_and_performance/cluster-compare/advanced-ref-config-customization.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="cluster-compare-manual-match_{context}"]
8+
= Configuring manual matching between CRs and templates
9+
10+
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.
11+
12+
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.
13+
14+
.Procedure
15+
16+
. Create a user configuration file to define the manual matching criteria:
17+
+
18+
.Example `user-config.yaml` file
19+
[source,yaml]
20+
----
21+
correlationSettings:
22+
manualCorrelation:
23+
correlationPairs:
24+
apps.v1.DaemonSet.kube-system.kindnet.yaml: "template_example.yaml" <1>
25+
----
26+
<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>`.
27+
28+
. Reference the user configuration file in a `cluster-compare` command by running the following command:
29+
+
30+
[source,terminal]
31+
----
32+
$ oc cluster-compare -r <path_to_reference_config>/metadata.yaml -c <path_to_user_config>/user-config.yaml <1>
33+
----
34+
<1> Specify the `user-config.yaml` file by using the `-c` option.

‎modules/cluster-compare-metadata-structure.adoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Module included in the following assemblies:
2+
3+
// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
7+
[id="cluster-compare-metadata-structure_{context}"]
8+
= Structure of the metadata.yaml file
9+
10+
The `metadata.yaml` file provides a central configuration point to define and configure the templates in a reference configuration.
11+
The file features a hierarchy of `parts` and `components`. `parts` are groups of `components` and `components` are groups of templates.
12+
Under each component, you can configure template dependencies, validation rules, and add descriptive metadata.
13+
14+
.Example metadata.yaml file
15+
[source,yaml]
16+
----
17+
apiVersion: v2
18+
parts: <1>
19+
- name: Part1 <2>
20+
components:
21+
- name: Component1 <3>
22+
<component1_configuration> <4>
23+
- name: Part2
24+
- name: Component2
25+
<component2_configuration>
26+
----
27+
<1> Every `part` typically describes a workload or a set of workloads.
28+
<2> Specify a `part` name.
29+
<3> Specify a `component` name.
30+
<4> Specify the configuration for a template. For example, define template relationships or configure what fields to use in a comparison.

‎modules/cluster-compare-output-description.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
3+
// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="cluster-compare-output-description_{context}"]
8+
= Configuring descriptions for the output
9+
10+
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.
11+
12+
.Procedure
13+
14+
* Create a `metadata.yaml` file to match your use case. Use the following structure as an example:
15+
+
16+
[source,yaml]
17+
----
18+
apiVersion: v2
19+
parts:
20+
- name: Part1
21+
description: |-
22+
General text for every template under this part, unless overridden.
23+
components:
24+
- name: Component1
25+
# With no description set, this inherits the description from the part above.
26+
OneOf:
27+
- path: Template1.yaml
28+
# This inherits the component description, if set.
29+
- path: Template2.yaml
30+
- path: Template3.yaml
31+
description: |-
32+
This template has special instructions that don't apply to the others.
33+
- name: Component2
34+
description: |-
35+
This overrides the part text with something more specific.
36+
Multi-line text is supported, at all levels.
37+
allOf:
38+
- path: RequiredTemplate1.yaml
39+
- path: RequiredTemplate2.yaml
40+
description: |-
41+
Required for important reasons.
42+
- path: RequiredTemplate3.yaml
43+
----

0 commit comments

Comments
 (0)