openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity
Files
ca07a69d71ecaa5bc1a2bd61f08111a00c0b6b59
openshift-docs/modules/cluster-compare-patching.adoc

203 lines
9.6 KiB
Plaintext
Raw Blame History

// Module included in the following assemblies:
// *scalability_and_performance/cluster-compare/advanced-ref-config-customization.adoc
:_mod-docs-content-type: PROCEDURE
[id="cluster-compare-patching_{context}"]
= Patching a reference configuration
In certain scenarios, you might need to patch the reference configuration to handle expected deviations in a cluster configuration. The plugin applies the patch during the comparison process, modifying the specified resource fields as defined in the patch file.
For example, you might need to temporarily patch a template because a cluster uses a deprecated field that is out-of-date with the latest reference configuration. Patched files are reported in the comparison output summary.
You can create a patch file in two ways:
* Use the `cluster-compare` plugin to generate a patch YAML file.
* Create your own patch file.
== Using the cluster-compare plugin to generate a patch
You can use the `cluster-compare` plugin to generate a patch for specific template files. The plugin adjusts the template to ensure it matches with the cluster custom resource (CR). Any previously valid differences in the patched template are not reported. The plugin highlights the patched files in the output.
.Procedure
. Generate patches for templates by running the following command:
+
[source,terminal]
----
$ 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>
----
+
* `-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.
. Optional: Review the patch file before applying to the reference configuration:
+
.Example `patch-config` file
[source,yaml]
----
- 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>
----
<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.
. Apply the patch to the reference configuration by running the following command:
+
[source,terminal]
----
$ oc cluster-compare -r <referenceConfigurationDirectory> -p <path_to_patches_file>
----
+
* `-r` specifies the path to the metadata.yaml file of the reference configuration.
* `-p` specifies the path to the patch file.
+
.Example output
[source,terminal]
----
...
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
----
== Creating a patch file manually
You can write a patch file to handle expected deviations in a cluster configuration.
[NOTE]
====
Patches have three possible values for the `type` field:
* `mergepatch` - Merges the JSON into the target template. Unspecified fields remain unchanged.
* `rfc6902` - Merges the JSON in the target template using `add`, `remove`, `replace`, `move`, and `copy` operations. Each operation targets a specific path.
* `go-template` - Defines a Golang template. The plugin renders the template using the cluster custom resource (CR) as input and generates either a `mergepatch` or `rfc6902` patch for the target template.
The following example shows the same patch using all three different formats.
====
.Procedure
. Create a patch file to match your use case. Use the following structure as an example:
+
.Example `patch-config`
[source,yaml]
----
- 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 }} }}
]'
}
----
<1> The patches uses the `kind`, `apiVersion`, `name`, and `namespace` fields to match the patch with the correct cluster CR.
. Apply the patch to the reference configuration by running the following command:
+
[source,terminal]
----
$ oc cluster-compare -r <referenceConfigurationDirectory> -p <path_to_patches_file>
----
+
* `-r` specifies the path to the metadata.yaml file of the reference configuration.
* `p` specifies the path to the patch file.
+
.Example output
[source,terminal]
----
...
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
----
View Git Blame Copy Permalink