Add flux deployment workaround (#40881)

* Add flux deployment workaround

* Apply suggestions from code review

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

* Specify teleport-kube-agent chart

* Add cspell ignore

---------

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

docs/cspell.json

@@ -445,6 +445,7 @@
     "fklvk",
     "flexi",
     "fluentd",
+    "fluxcd",
     "ftmg",
     "fullchain",
     "gacc",

docs/pages/upgrading/cloud-kubernetes.mdx

@@ -124,23 +124,26 @@ To suspend automatic updates for an agent, annotate the agent deployment with
 `annotations.deployment` value in Helm, or by patching the deployment directly
 with `kubectl`.
 
-## ArgoCD deployments
+## GitOps
 
-Automatic updates is not currently compatible with ArgoCD deployments. The Helm chart
-owns the version of the `teleport-agent` resource, so when the `teleport-agent-updater`
-modifies the image version of the `teleport-agent` resource, ArgoCD reports the `teleport-agent`
-resource as `OutOfSync`.
+Automatic updates are incompatible with some GitOps tools used for continuous deployment.
+The `teleport-kube-agent` Helm chart owns the version of the `teleport-agent` resource,
+so when the `teleport-agent-updater` modifies the image version of the `teleport-agent`
+resource, the GitOps tool will detect a drift or a diff in the `teleport-agent` resource.
 
+### ArgoCD deployments
+
+After an automatic update, ArgoCD reports the `teleport-agent` resource as `OutOfSync`.
 As a workaround to this problem use a [Diff Customization](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/#diffing-customization)
-to ignore the difference in image version. This can be done by ignoring differences
-of the `image` field. Here is an example deployment using the name `teleport-agent`
-and namespace `teleport`.
+to ignore the difference in image version. Here is an example deployment using the
+name `teleport-agent` and namespace `teleport`.
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
   name: teleport-agent
+  namespace: teleport
 spec
   ignoreDifferences:
   - group: apps
@@ -152,6 +155,31 @@ spec
 ...
 ```
 
+### FluxCD deployments
+
+After an automatic update, FluxCD reports a `DriftDetected` event. As a workaround
+to this problem modify the [drift detection](https://fluxcd.io/flux/components/helm/helmreleases/#drift-detection)
+configuration to ignore the difference in image version. Here is an example deployment
+using the name `teleport-agent` and namespace `teleport`.
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta2
+kind: HelmRelease
+metadata:
+  name: teleport-agent
+  namespace: teleport
+spec
+  driftDetection:
+    mode: enabled
+    ignore:
+    - paths: ["/spec/template/spec/containers/0/image"]
+      target:
+        kind: StatefulSet
+        name: teleport-agent
+        namespace: teleport
+...
+```
+
 ## Manually upgrading agents
 
 Run the following commands to upgrade Teleport agents running on Kubernetes.