docs: endorse secrets operators, caution against plugins (argoproj#21629

)

Signed-off-by: Michael Crenshaw <[email protected]>

docs/operator-manual/secret-management.md

@@ -1,29 +1,43 @@
 # Secret Management
 
-Argo CD is un-opinionated about how secrets are managed. There are many ways to do it, and there's no one-size-fits-all solution.
+There are two general ways to populate secrets when doing GitOps: on the destination cluster, or in Argo CD during 
+manifest hydration. We strongly recommend the former, as it is more secure and provides a better user experience.
 
-Many solutions use plugins to inject secrets into the application manifests. See [Mitigating Risks of Secret-Injection Plugins](#mitigating-risks-of-secret-injection-plugins)
-below to make sure you use those plugins securely.
+For discussion, see [#1364](https://github.com/argoproj/argo-cd/issues/1364).
 
-Here are some ways people are doing GitOps secrets:
+## Destination Cluster Secret Management
 
-* [Bitnami Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets)
-* [External Secrets Operator](https://github.com/external-secrets/external-secrets)
-* [Hashicorp Vault](https://www.vaultproject.io)
-* [Bank-Vaults](https://bank-vaults.dev/)
-* [Helm Secrets](https://github.com/jkroepke/helm-secrets)
-* [Kustomize secret generator plugins](https://github.com/kubernetes-sigs/kustomize/blob/fd7a353df6cece4629b8e8ad56b71e30636f38fc/examples/kvSourceGoPlugin.md#secret-values-from-anywhere)
-* [aws-secret-operator](https://github.com/mumoshu/aws-secret-operator)
-* [KSOPS](https://github.com/viaduct-ai/kustomize-sops#argo-cd-integration)
-* [argocd-vault-plugin](https://github.com/argoproj-labs/argocd-vault-plugin)
-* [argocd-vault-replacer](https://github.com/crumbhole/argocd-vault-replacer)
-* [Kubernetes Secrets Store CSI Driver](https://github.com/kubernetes-sigs/secrets-store-csi-driver)
-* [Vals-Operator](https://github.com/digitalis-io/vals-operator)
-* [argocd-secret-replacer](https://github.com/mmalyska/argocd-secret-replacer)
+In this approach, secrets are populated on the destination cluster, and Argo CD does not need to directly manage them.
+[Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) and [External Secrets Operator](https://github.com/external-secrets/external-secrets)
+are examples of this style of secret management.
 
-For discussion, see [#1364](https://github.com/argoproj/argo-cd/issues/1364)
+This approach has two main advantages:
 
-## Mitigating Risks of Secret-Injection Plugins
+1) Security: Argo CD does not need to have access to the secrets, which reduces the risk of leaking them.
+2) User Experience: Secret updates are decoupled from app sync operations, which reduces the risk of unintentionally
+   applying Secret updates during an unrelated release.
+
+We strongly recommend this style of secret management.
+
+## Argo CD Hydration-Based Secret Management
+
+In this approach, Argo CD's "manifest hydration" step is used to inject secrets. This may be done using a 
+[Config Management Plugin](config-management-plugins.md) like [argocd-vault-plugin](https://github.com/argoproj-labs/argocd-vault-plugin).
+
+**We strongly caution against this style of secret management**, as it has several disadvantages:
+
+1) Security: Argo CD needs access to the secrets, which increases the risk of leaking them. Argo CD stores hydrated 
+   manifests in plaintext in its Redis cache, so injecting secrets into the manifests increases risk.
+2) User Experience: Secret updates are coupled with app sync operations, which increases the risk of unintentionally
+   applying Secret updates during an unrelated release.
+3) Rendered Manifests Pattern: This approach is incompatible with the "Rendered Manifests" pattern, which is 
+   increasingly becoming a best practice for GitOps and which Argo CD supports via the [source hydrator](../user-guide/source-hydrator.md).
+
+Many users have already adopted hydration-based solutions, and we understand that migrating to an operator-based 
+solution can be a significant effort. Argo CD will continue to support hydration-based secret management, but we will 
+not prioritize new features or improvements that solely support this style of secret management.
+
+### Mitigating Risks of Secret-Injection Plugins
 
 Argo CD caches the manifests generated by plugins, along with the injected secrets, in its Redis instance. Those
 manifests are also available via the repo-server API (a gRPC service). This means that the secrets are available to
@@ -34,4 +48,3 @@ Consider these steps to mitigate the risks of secret-injection plugins:
 1. Set up network policies to prevent direct access to Argo CD components (Redis and the repo-server). Make sure your
    cluster supports those network policies and can actually enforce them.
 2. Consider running Argo CD on its own cluster, with no other applications running on it.
-