[enterprise-4.19] TELCODOCS#1992: Adding OpenAPI support for custom resources with ACM policy generator

edge_computing/policygenerator_for_ztp/ztp-configuring-managed-clusters-policygenerator.adoc

@@ -11,6 +11,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can customize how {rh-rhacm-first} uses `{policy-gen-cr}` CRs to generate `Policy` CRs that configure the managed clusters that you provision.
 
 Using {rh-rhacm} and `{policy-gen-cr}` CRs is the recommended approach for managing policies and deploying them to managed clusters.
@@ -72,6 +73,8 @@ include::modules/ztp-removing-content-from-managed-clusters.adoc[leveloffset=+1]
 
 include::modules/ztp-definition-of-done-for-ztp-installations.adoc[leveloffset=+1]
 
+include::modules/ztp-configuring-open-api-schema-for-patching.adoc[leveloffset=+1]
+
 :!policy-gen-cr:
 :!policy-prefix:
 :!argocd-folder:

modules/ztp-configuring-open-api-schema-for-patching.adoc

@@ -0,0 +1,79 @@
+// Module included in the following assemblies:
+//
+// * scalability_and_performance/ztp_far_edge/ztp-configuring-managed-clusters-policies.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-configuring-open-api-schema-for-patching_{context}"]
+= Configuring an OpenAPI schema for patching list fields by using the PolicyGenerator CR
+
+[role="_abstract"]
+You can configure an OpenAPI schema in the `PolicyGenerator` custom resource (CR) to control how list fields are merged when patching non-core Kubernetes objects.
+
+By default, patching list fields can replace entire lists when the resource does not define merge behavior. An OpenAPI schema defines how list items are uniquely identified and merged during policy generation.
+
+.Prerequisites
+
+* You have created a `PolicyGenerator` CR.
+* You have access to a running cluster if you need to generate a schema.
+
+.Procedure
+
+. Obtain an OpenAPI schema for the resources that you want to patch:
+
+.. If an OpenAPI schema is available for the custom resource that you want to patch, use that schema file.
+.. If a schema is not available, generate it from an active cluster by running the following command:
++
+[source,bash]
+----
+kustomize openapi fetch
+----
+
+. Edit the generated schema file to keep only the resource definitions that you need to patch.
++
+Removing unrelated definitions simplifies the schema and reduces maintenance effort.
+
+. Define merge behavior for list fields that you want to patch. For each list of objects that you want to patch, add fields that specify how list items are uniquely identified and merged. For example:
++
+[source,yaml]
+----
+"x-kubernetes-patch-merge-key": "name"
+"x-kubernetes-patch-strategy": "merge"
+----
++
+* `x-kubernetes-patch-merge-key` specifies the field that uniquely identifies an object in the list.  
+  For example, setting this field to `name` uses the `name` field to identify list items.
+* `x-kubernetes-patch-strategy` specifies how the patch is applied to the identified list item. The following are the supported values:
+** `merge`: Merges the fields from the patch into the existing list item.
+** `replace`: Replaces the entire list item identified by the merge key with the patch content.
+
+. Save the schema file in the directory that contains the `kustomization.yaml` file.
+
+. Reference the OpenAPI schema in the `kustomization.yaml` file:
++
+[source,yaml]
+----
+openapi:
+  path: schema.json
+----
+
+. Configure the OpenAPI schema path in the `PolicyGenerator` CR:
++
+.Example `PolicyGenerator` CR for patching list fields by using an OpenAPI schema
+[source,yaml]
+----
+apiVersion: policy.open-cluster-management.io/v1
+kind: PolicyGenerator
+metadata:
+  name: policy-generator-example
+policies:
+  - name: myapp
+    manifests:
+      - path: input-kustomize/
+        patches: []
+        openapi:
+          path: schema.json
+----
+
+. Generate or apply the policies by using the policy generator.
++
+The policy generator passes the OpenAPI schema to Kustomize to control how list fields are patched.