Prerequisites: gitops, reconciliation, kubernetes
Argo CD is a controller you install into a Kubernetes cluster to do gitops: it watches a git repository, compares the manifests there against the live cluster, and reconciles the cluster to match. It is one concrete implementation of the reconciliation loop with git as the desired state. It is not magic and it is not outside the cluster. It is an ordinary set of Kubernetes workloads running in a namespace called argocd, and once you understand that, installing it and even letting it manage itself stop being surprising. The reference is the Argo CD documentation.
What it is made of
Argo CD is not a single binary. It is a handful of cooperating components, each its own workload. You can read them straight out of the upstream install manifest without applying anything, which is the best way to convince yourself there is nothing exotic here.
curl -sL https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml \
| grep -E '^kind:|^ name:' | grep -A1 -E 'Deployment|StatefulSet'The pieces that matter:
- application-controller (a StatefulSet). This is the reconciler itself. It holds the loop from reconciliation: for each application you have defined, it fetches the desired manifests, compares them to the live objects, marks the app synced or out of sync, and (if told to) applies the difference. When you read about Argo CD “reconciling”, this is the process doing it.
- repo-server (a Deployment). It clones your git repository and turns whatever is at the given path into plain Kubernetes manifests. If the path is raw YAML it just reads it; if it is a Helm chart it runs
helm template; if it is a Kustomize overlay it runskustomize build. The controller never talks to git directly; it asks the repo-server “what should be there”, and the repo-server answers with rendered YAML. - server, usually called the api-server (a Deployment). It serves the web UI, the
argocdCLI, and the gRPC/REST API. It is the human-facing front door and is not in the reconciliation path at all; you could delete it and reconciliation would continue, you just could not log in to watch. - redis (a Deployment). A cache so the controller and repo-server do not recompute manifests and cluster state from scratch every loop. It holds no source of truth; if it is wiped, Argo CD repopulates it.
- dex (a Deployment, optional). An identity broker for single sign-on. A homelab can ignore it and use the built-in
adminaccount.
Everything in that list is a Deployment or a StatefulSet. That is the whole point: Argo CD is just Kubernetes workloads, so it can be installed by applying YAML, version controlled like anything else, and ultimately reconciled by a copy of itself.
How it knows what to do
Installing Argo CD also registers its custom resource definitions, which teach the cluster three new object kinds:
- Application: one deployable unit, a mapping from “this path in this git repo” to “these objects in this cluster and namespace”. This is the object you spend almost all your time writing, and it has its own note, application.
- ApplicationSet: a template that generates many Applications from a generator, for when you would otherwise hand-write near-identical Application files. Useful later; not needed to bootstrap.
- AppProject: a grouping of Applications with guardrails on what repos, clusters, and namespaces they are allowed to touch. The install ships a
defaultproject that permits everything, which is fine for a single-tenant homelab.
After install, you confirm the kinds exist with:
kubectl get crd | grep argoproj.ioPull, not push
Argo CD runs inside the cluster it manages and pulls from git. Nothing on your laptop pushes manifests into devata. This matters for two reasons. Credentials to the cluster never have to leave the cluster, because the thing applying changes is already inside it. And the cluster keeps reconciling even when your laptop is closed, because the loop is running on devata, not on you. The only thing you push is a commit to git, and Argo CD comes and gets it.
Because Argo CD is just workloads plus an Application that can point at any git path, it can point at the very path that installed it and manage its own upgrades. That self-management is the trick the bootstrap walkthrough uses, and it relies on the pattern in app-of-apps.