doc: ArgoCD integration

README.md

@@ -1142,6 +1142,36 @@ For more examples, see the [examples/README.md](https://github.com/roboll/helmfi
 
 - [renovate](https://github.com/renovatebot/renovate) automates chart version updates. See [this PR for more information](https://github.com/renovatebot/renovate/pull/5257).
   - For updating container image tags and git tags embedded within helmfile.yaml and values, you can use [renovate's regexManager](https://docs.renovatebot.com/modules/manager/regex/). Please see [this comment in the renovate repository](https://github.com/renovatebot/renovate/issues/6130#issuecomment-624061289) for more information.
+- [ArgoCD Integration](#argocd-integration)
+
+### ArgoCD Integration
+
+Use [ArgoCD](https://argoproj.github.io/argo-cd/) with `helmfile template` for GitOps.
+
+ArgoCD has support for kustomize/manifests/helm chart by itself. Why bother with Helmfile?
+
+The reasons may vary:
+
+1. You do want to manage applications with ArgoCD, while letting Helmfile manage infrastructure-related components like Calico/Cilium/WeaveNet, Linkerd/Istio, and ArgoCD itself.
+  - This way, any application deployed by ArgoCD has access to all the infrastructure.
+  - Of course, you can use ArgoCD's [Sync Waves and Phases](https://argoproj.github.io/argo-cd/user-guide/sync-waves/) for ordering the infrastructure and application installations. But it may be difficult to separate the concern between the infrastructure and apps and annotate K8s resources consistently when you have different teams for managing infra and apps.
+2. You want to review the exact K8s manifests being applied on pull-request time, before ArgoCD syncs.
+  - This is often better than using a kind of `HelmRelease` custom resources that obfuscates exactly what manifests are being applied, which makes reviewing harder.
+3. Use Helmfile as the single-pane of glass for all the K8s resources deployed to your cluster(s).
+  - Helmfile can reduce repetition in K8s manifests across ArgoCD application
+
+For 1, you run `helmfile apply` on CI to deploy ArgoCD and the infrastructure components.
+
+> helmfile config for this phase often reside within the same directory as your Terraform project. So connecting the two with [terraform-provider-helmfile](https://github.com/mumoshu/terraform-provider-helmfile) may be helpful
+
+For 2, another app-centric CI or bot should run `helmfile template --output-dir-template gitops//{{.Release.Name}} && cd gitops && git add . && git commit && git push` to render/commit manifests,
+so that they can be deployed by Argo CD as usual.
+
+Recommendations:
+
+- Do create ArgoCD `Application` custom resource per Helm/Helmfile release, each point to respective sub-directory generated by `helmfile template --output-dir-template`
+- If you don't directly push it to the main Git branch and instead go through a pull-request, do lint rendered manifests on your CI, so that you can catch easy mistakes earlier/before ArgoCD finally deploys it
+- See [this ArgoCD issue](https://github.com/argoproj/argo-cd/issues/2143#issuecomment-570478329) for why you may want this, and see [this helmfile issue](https://github.com/roboll/helmfile/pull/1357) for how `--output-dir-template` works.
 
 # Attribution