add docs

doc/deployments/argocd.md

@@ -1,4 +1,49 @@
 # Argo CD
+## Overview
+### Deployment of Argo CD
+We deploy Argo CD via helmfile and the community helm charts: https://argoproj.github.io/argo-helm/
+- see [/k8s/helmfile/argo-cd.yaml](../../k8s/helmfile/argo-cd.yaml)
+
+It's basic configuration lives in the values files `argo-cd-base.values.yaml.gotmpl` for each environment.
+ - [production](../../k8s/helmfile/env/production/argo-cd-base.values.yaml.gotmpl)
+     - [staging](../../k8s/helmfile/env/staging/argo-cd-base.values.yaml.gotmpl)
+    - [local](../../k8s/helmfile/env/local/argo-cd-base.values.yaml.gotmpl)
+
+Currently this means each environment gets it's own instance of Argo CD, which in turn always deploys to the cluster it lives in. We may want to change this in the future, if this prevents us from using certain features or workflows.
+
+### Application configuration
+There are two more charts we use to configure our project & applications:
+- [argocd-config](../../charts/argocd-config/)
+  - gets deployed by helmfile
+  - defines the ["app-of-apps"](https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/) `Application` 
+- [argocd-apps](../../charts/argocd-apps/)
+  - gets deployed by Argo CD
+  - defines the `Application` resources for our actual helm releases
+
+The values of the first chart get passed on to the second one, so we can infer which environment we are running in.
+
+### Values files
+After trying out different ways of templating our way through this, we currently settled with a script to generate plain yaml files:
+- the bash script: [/bin/generate/values](../../bin/generate-values)
+- the values files: [/k8s/argocd/](../../k8s/argocd/)
+
+These are generated by helmfile, which in turn reads the value files in [/k8s/helmfile/env/](../../k8s/helmfile/env/) like we are used to.
+
+#### [/bin/generate/values](../../bin/generate-values)
+```
+ $ ./bin/generate-values 
+error: missing environment
+
+usage: generate-values <environment> <release-name> [output-file-template]
+```
+The script can be run like `./bin/generate-values local ui` where `local` could be `staging` or `production` and `ui` any other helmfile release. The third parameter let's you define a different helmfile than `k8s/helmfile/helmfile.yaml`. This is needed for the CI script. Once we moved all components to Argo we could create a Makefile target that generates/updates all values files, for our convenience.
+
+#### CI - [check-generated-values.yml](../../.github/workflows/check-generated-values.yml)
+This GitHub workflow runs the script to check if the checked-in values files are actually up to date. It does this by iterating over each generated values file that is present in `k8s/argocd/` and runs `generate-values` to compare it against.
+
+### Self-Healing
+[Automatic Self-Healing](https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/#automatic-self-healing) is currently disabled for the local environment. This way, we still can use skaffold to replace resources that get deployed by Argo CD. Otherwise Argo CD would immediately replace them again with the image that is configured in the values files.
+
 ## Admin access
 > Caution! Admin access should only happen in rare circumstances (testing/diagnosing, for example)
 > as we want to maintain the configuration for everything in git.