Merge pull request #93606 from slovern/TELCODOCS-2329

TELCODOCS-2329 - ACM PolicyGenerator RAN limitations

Author: xenolinux

modules/cnf-topology-aware-lifecycle-manager-troubleshooting.adoc

@@ -469,3 +469,32 @@ $ oc describe pod -n openshift-talo-pre-cache <pod name>
 ----
 $ oc describe job -n openshift-talo-pre-cache pre-cache
 ----
+
+[discrete]
+[id="talo-troubleshooting-pre-placement-tolerations_{context}"]
+=== Matching policies and `ManagedCluster` CRs before the managed cluster is available
+
+Issue:: You want {rh-rhacm} to match policies and managed clusters before the managed clusters become available.
++
+Resolution:: To ensure that {cgu-operator} correctly applies the {rh-rhacm} policies specified in the `spec.managedPolicies` field of the `ClusterGroupUpgrade` (CGU) CR, {cgu-operator} needs to match these policies to the managed cluster before the managed cluster is available. 
+The {rh-rhacm} `PolicyGenerator` uses the generated `Placement` CR to do this automatically. 
+By default, this `Placement` CR includes the necessary tolerations to ensure proper {cgu-operator} behavior. 
++
+The expected `spec.tolerations` settings in the `Placement` CR are as follows:
++
+[source,yaml]
+----
+#…​
+  tolerations:
+    - key: cluster.open-cluster-management.io/unavailable
+     operator: Exists
+    - key: cluster.open-cluster-management.io/unreachable
+     operator: Exists
+#…​
+----
++
+If you use a custom `Placement` CR instead of the one generated by the {rh-rhacm} `PolicyGenerator`, include these tolerations in that `Placement` CR.
++
+For more information on placements in {rh-rhacm}, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html-single/clusters/index#placement-overview[Placement overview].
++
+For more information on tolerations in {rh-rhacm}, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/latest/html-single/clusters/index#taints-tolerations-managed[Placing managed clusters by using taints and tolerations].

modules/ztp-pgt-config-best-practices.adoc

@@ -15,3 +15,10 @@ Consider the following best practices when customizing site configuration `{poli
 * `MachineConfig` CRs should be included as `extraManifests` in the `SiteConfig` CR so that they are applied during installation. This can reduce the overall time taken until the cluster is ready to deploy applications.
 
 * `{policy-gen-cr}` CRs should override the channel field to explicitly identify the desired version. This ensures that changes in the source CR during upgrades does not update the generated subscription.
+
+* The default setting for `policyDefaults.consolidateManifests` is `true`. This is the recommended setting for DU profile. Setting it to `false` might impact large scale deployments.
+
+* The default setting for `policyDefaults.orderPolicies` is `false`. This is the recommended setting for DU profile.  
+After the cluster installation is complete and a cluster becomes `Ready`, {cgu-operator} creates a `ClusterGroupUpgrade` CR corresponding to this cluster. 
+The `ClusterGroupUpgrade` CR contains a list of ordered policies defined by the `ran.openshift.io/ztp-deploy-wave` annotation.
+If you use the `{policy-gen-cr}` CR to change the order of the policies, conflicts might occur and the configuration might not be applied.