From 392746f72cfe4fac5c2d5ed1c0c58421c83cfcf5 Mon Sep 17 00:00:00 2001
From: alexander-demicev <alexandr.demicev@suse.com>
Date: Thu, 12 Oct 2023 20:31:38 +0200
Subject: [PATCH] Document json patches usage

Signed-off-by: alexander-demicev <alexandr.demicev@suse.com>
---
 docs/README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/README.md b/docs/README.md
index 1921b763..8c30d722 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -754,3 +754,35 @@ spec:
   additionalManifests:
     name: additional-manifests
 ```
+
+## Patching provider manifests
+
+Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider
+manifests `spec.ResourcePatches` has to be used where an array of patches can be specified:
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
+spec:
+  resourcePatches:
+    - |
+apiVersion: v1
+kind: Service
+metadata:
+labels:
+    test-label: test-value
+```
+
+More information about JSON merge patches can be found here https://datatracker.ietf.org/doc/html/rfc7396
+
+There are couple of rules for the patch to match a manifest:
+
+- The `kind` field must match the target object.
+- If `apiVersion` is specified it will only be applied to matching objects.
+- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind.
+- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects.
+- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace.