Document diff.comparePatches
@@ -128,3 +128,40 @@ stringData:
Note: If you don't add it any server's public key will be trusted and added.
+# Troubleshooting
+
+### Fleet deployment stuck in modified state
+
+When you deploy bundles to Fleet, some of the components are modified, and this causes the "modified" flag in the Fleet environment.
+
+To ignore the modified flag for the differences between the Helm install generated by `fleet.yaml` and the resource in your cluster, add a `diff.comparePatches` to the `fleet.yaml` for your Deployment, as shown in this example:
+
+
+```yaml
+defaultNamespace: <namespace name>
+helm:
+ releaseName: <release name>
+ repo: <repo name>
+ chart: <chart name>
+diff:
+ comparePatches:
+ - apiVersion: apps/v1
+ kind: Deployment
+ operations:
+ - {"op":"remove", "path":"/spec/template/spec/hostNetwork"}
+ - {"op":"remove", "path":"/spec/template/spec/nodeSelector"}
+ - {"op":"remove", "path":"/spec/template/spec/priorityClassName"}
+ - {"op":"remove", "path":"/spec/template/spec/tolerations"}
+```
+
+To determine which operations should be removed, observe the logs from `fleet-agent` on the target cluster. You should see entries similar to the following:
+
+```text
+level=error msg="bundle monitoring-monitoring: deployment.apps monitoring/monitoring-monitoring-kube-state-metrics modified {\"spec\":{\"template\":{\"spec\":{\"hostNetwork\":false}}}}"
+```
+
+Based on the above log, you can add the following entry to remove the operation:
+
+```json
+{"op":"remove", "path":"/spec/template/spec/hostNetwork"}
+```
