In GitOps, what does it mean to bootstrap a cluster, and why is the GitOps agent's own configuration usually kept in the Git path that the agent itself reconciles?

## The one imperative step GitOps says the cluster's desired state lives in Git and an in-cluster agent continuously converges reality toward it. That description has a hole in it at exactly one place: something has to put the agent on the cluster in the first place, and something has to tell the agent which repository to read. That step is bootstrapping. Concretely it does three things: 1. installs the GitOps controller into the cluster (a set of workloads plus the permissions it needs); 2. gives it a **source** — a repository or OCI artifact URL, a revision, and a path inside it; 3. gives it the **credentials** to read that source, and to decrypt anything encrypted inside it. Only after that does the loop described in the marketing diagram start running. Every mature GitOps tool ships a bootstrap command precisely because this step exists and cannot itself be reconciled from Git. ## Chicken and egg The interesting design move is what happens *next*. A naive setup leaves the agent outside the system it manages: the workloads are declarative and reviewed, but the agent was installed by hand, upgraded by hand, and reconfigured by hand. Nobody can say from the repository which version of the controller is running, and a cluster rebuild depends on somebody remembering the flags they typed. The standard fix is to make the agent one of the things the agent manages. Its manifests — the controller version, its source definitions, its root application, its RBAC — are committed into the same path it reconciles. On the first bootstrap the imperative install creates a controller which then reads Git, finds a declaration of itself, and adopts it. Afterwards, upgrading from one controller version to the next is a commit; adding a second source repository is a commit; the running state is legible from the repo. ## What this buys you **Reproducibility.** Cluster rebuild becomes: provision an empty cluster, run one bootstrap command, wait. There is no ordered runbook of `kubectl` commands to replay, and no drift between what the runbook says and what someone actually did last time. **Auditability.** The controller's own version and configuration go through the same review as application changes, so a change to the thing that has cluster-admin-level power is not the one change that skips review. **Fleet consistency.** When fifty clusters bootstrap from paths generated the same way, they all converge on the same platform baseline instead of each drifting to whatever was installed the day it was created. ## What still cannot live in Git The seed. At minimum: - a reachable cluster and an admin credential for it, produced by whatever provisions clusters; - network reachability from cluster to Git/OCI source (typically egress-only); - the read credential for the source — a deploy key or token — which obviously cannot be stored inside the repository it unlocks; - decryption material for encrypted secrets in the repo; - any cloud identity binding the controller needs. These are handed to the cluster by the provisioning step or an external secret store. It is also worth being explicit that Git holds *declarations*, not *data*: rebuilding a cluster from Git restores the objects, not the contents of persistent volumes or a database. ## The failure mode to know Self-management creates a way to lock yourself out. If a commit breaks the agent's own definition — a controller image tag that does not exist, a source URL typo, RBAC that removes its own permissions — the agent may apply the change, break, and then be unable to pull the commit that fixes it. Recovery is imperative: re-run the bootstrap, or apply the corrected manifest directly with cluster credentials. Because of that, teams usually treat the agent's own path differently: stricter review, a separate change window from application changes, and an upgrade rolled to one cluster before the fleet. A useful habit is to keep the ability to bootstrap from scratch tested — if the only path back is a heroic manual repair, the reproducibility claim was never verified. ```bash # shape of the seed (illustrative, tool-agnostic): # 1. provision cluster -> admin kubeconfig # 2. create read credential -> deploy key / token # 3. install agent + point at repo -> the only imperative step # 4. everything else -> commits ```