Chapter 6. Comparing cluster configurations

Procedure

1. Create a metadata.yaml file to match your use case. Use the following structure as an example:

   apiVersion: v2
   parts:
   - name: Part1
     components:
     - name: Example
       allOf:
       - path: example.yaml
         config:
           perField:
           - pathToKey: spec.bigTextBlock 

   1

   
             inlineDiffFunc: regex 

   2

   Copy to Clipboard Toggle word wrap

   1

   Specifies the field for inline validation.

   2

   Enables inline validation using regular expressions.

2. Use a regular expression to validate the field in the associated template:

   apiVersion: v1
   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.

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a metadata.yaml file to match your use case. Use the following structure as an example:

   apiVersion: v2
   parts:
   - name: Part1
     components:
     - name: Example
       allOf:
       - path: example.yaml
         config:
           perField:
           - pathToKey: data.username 

   1

   
             inlineDiffFunc: regex 

   2

   
           - pathToKey: spec.bigTextBlock 

   3

   
             inlineDiffFunc: capturegroups 

   4

   Copy to Clipboard Toggle word wrap

   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.

2. Use a regular expression to validate the field in the associated template:

   apiVersion: v1
   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]+).

   Copy to Clipboard Toggle word wrap

   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:

   WARNING: Capturegroup (?<username>…) matched multiple values: « mismatchuser | exampleuser »

   Copy to Clipboard Toggle word wrap

Procedure

1. Generate patches for templates by running the following command:

   $ oc cluster-compare -r <path_to_reference_config>/metadata.yaml -o 'generate-patches' --override-reason "A valid reason for the override" --generate-override-for "<template1_path>" --generate-override-for "<template2_path>" > <path_to_patches_file>

   Copy to Clipboard Toggle word wrap
   • -r specifies the path to the metadata.yaml file of the reference configuration.
   • -o specifies the output format. To generate a patch output, you must use the generate-patches value.
   • --override-reason describes the reason for the patch.

   • --generate-override-for specifies a path to the template that requires a patch.

     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.

   • <path_to_patches_file> specifies the filename and path for your patch.

2. Optional: Review the patch file before applying to the reference configuration:

   Example patch-config file

   - apiVersion: storage.k8s.io/v1
     kind: StorageClass
     name: crc-csi-hostpath-provisioner
     patch: '{"provisioner":"kubevirt.io.hostpath-provisioner"}' 

   1

   
     reason: A valid reason for the override
     templatePath: optional/local-storage-operator/StorageClass.yaml 

   2

   
     type: mergepatch 

   3

   Copy to Clipboard Toggle word wrap

   1

   The plugin patches the fields in the template to match the CR.

   2

   The path to the template.

   3

   The mergepath option merges the JSON into the target template. Unspecified fields remain unchanged.

3. Apply the patch to the reference configuration by running the following command:

   $ oc cluster-compare -r <referenceConfigurationDirectory> -p <path_to_patches_file>

   Copy to Clipboard Toggle word wrap
   • -r specifies the path to the metadata.yaml file of the reference configuration.

   • -p specifies the path to the patch file.

     Example output

     ...
     
     Cluster CR: storage.k8s.io/v1_StorageClass_crc-csi-hostpath-provisioner
     Reference File: optional/local-storage-operator/StorageClass.yaml
     Description: Component description
     Diff Output: None
     Patched with patch
     Patch Reasons:
     - A valid reason for the override
     
     ...
     
     No CRs are unmatched to reference CRs
     Metadata Hash: bb2165004c496b32e0c8509428fb99c653c3cf4fba41196ea6821bd05c3083ab
     Cluster CRs with patches applied: 1

     Copy to Clipboard Toggle word wrap

Procedure

1. Create a patch file to match your use case. Use the following structure as an example:

   Example patch-config

   - apiVersion: v1 

   1

   
     kind: Namespace
     name: openshift-storage
     reason: known deviation
     templatePath: namespace.yaml
     type: mergepatch
     patch: '{"metadata":{"annotations":{"openshift.io/sa.scc.mcs":"s0:c29,c14","openshift.io/sa.scc.supplemental-groups":"1000840000/10000","openshift.io/sa.scc.uid-range":"1000840000/10000","reclaimspace.csiaddons.openshift.io/schedule":"@weekly","workload.openshift.io/allowed":null},"labels":{"kubernetes.io/metadata.name":"openshift-storage","olm.operatorgroup.uid/ffcf3f2d-3e37-4772-97bc-983cdfce128b":"","openshift.io/cluster-monitoring":"false","pod-security.kubernetes.io/audit":"privileged","pod-security.kubernetes.io/audit-version":"v1.24","pod-security.kubernetes.io/warn":"privileged","pod-security.kubernetes.io/warn-version":"v1.24","security.openshift.io/scc.podSecurityLabelSync":"true"}},"spec":{"finalizers":["kubernetes"]}}'
   - name: openshift-storage
     apiVersion: v1
     kind: Namespace
     templatePath: namespace.yaml
     type: rfc6902
     reason: known deviation
     patch: '[
       {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.mcs", "value": "s0:c29,c14"},
       {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.supplemental-groups", "value": "1000840000/10000"},
       {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.uid-range", "value": "1000840000/10000"},
       {"op": "add", "path": "/metadata/annotations/reclaimspace.csiaddons.openshift.io~1schedule", "value": "@weekly"},
       {"op": "remove", "path": "/metadata/annotations/workload.openshift.io~1allowed"},
       {"op": "add", "path": "/metadata/labels/kubernetes.io~1metadata.name", "value": "openshift-storage"},
       {"op": "add", "path": "/metadata/labels/olm.operatorgroup.uid~1ffcf3f2d-3e37-4772-97bc-983cdfce128b", "value": ""},
       {"op": "add", "path": "/metadata/labels/openshift.io~1cluster-monitoring", "value": "false"},
       {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1audit", "value": "privileged"},
       {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1audit-version", "value": "v1.24"},
       {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1warn", "value": "privileged"},
       {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1warn-version", "value": "v1.24"},
       {"op": "add", "path": "/metadata/labels/security.openshift.io~1scc.podSecurityLabelSync", "value": "true"},
       {"op": "add", "path": "/spec", "value": {"finalizers": ["kubernetes"]}}
       ]'
   - apiVersion: v1
     kind: Namespace
     name: openshift-storage
     reason: "known deviation"
     templatePath: namespace.yaml
     type: go-template
     patch: |
       {
           "type": "rfc6902",
           "patch": '[
               {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.mcs", "value": "s0:c29,c14"},
               {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.supplemental-groups", "value": "1000840000/10000"},
               {"op": "add", "path": "/metadata/annotations/openshift.io~1sa.scc.uid-range", "value": "1000840000/10000"},
               {"op": "add", "path": "/metadata/annotations/reclaimspace.csiaddons.openshift.io~1schedule", "value": "@weekly"},
               {"op": "remove", "path": "/metadata/annotations/workload.openshift.io~1allowed"},
               {"op": "add", "path": "/metadata/labels/kubernetes.io~1metadata.name", "value": "openshift-storage"},
               {"op": "add", "path": "/metadata/labels/olm.operatorgroup.uid~1ffcf3f2d-3e37-4772-97bc-983cdfce128b", "value": ""},
               {"op": "add", "path": "/metadata/labels/openshift.io~1cluster-monitoring", "value": "false"},
               {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1audit", "value": "privileged"},
               {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1audit-version", "value": "v1.24"},
               {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1warn", "value": "privileged"},
               {"op": "add", "path": "/metadata/labels/pod-security.kubernetes.io~1warn-version", "value": "v1.24"},
               {"op": "add", "path": "/metadata/labels/security.openshift.io~1scc.podSecurityLabelSync", "value": "true"},
               {"op": "add", "path": "/spec", "value": {"finalizers": {{ .spec.finalizers | toJson }} }}
           ]'
       }

   Copy to Clipboard Toggle word wrap

   1

   The patches uses the kind, apiVersion, name, and namespace fields to match the patch with the correct cluster CR.

2. Apply the patch to the reference configuration by running the following command:

   $ oc cluster-compare -r <referenceConfigurationDirectory> -p <path_to_patches_file>

   Copy to Clipboard Toggle word wrap
   • -r specifies the path to the metadata.yaml file of the reference configuration.

   • p specifies the path to the patch file.

     Example output

     ...
     
     Cluster CR: storage.k8s.io/v1_StorageClass_crc-csi-hostpath-provisioner
     Reference File: namespace.yaml
     Description: Component description
     Diff Output: None
     Patched with patch
     Patch Reasons:
     - known deviation
     - known deviation
     - known deviation
     
     ...
     
     No CRs are unmatched to reference CRs
     Metadata Hash: bb2165004c496b32e0c8509428fb99c653c3cf4fba41196ea6821bd05c3083ab
     Cluster CRs with patches applied: 1

     Copy to Clipboard Toggle word wrap