ArgoCD

ArgoCD is a Kubernetes controller that keeps a cluster equal to what a Git repository says. The Azure Web App Blueprint runs one ArgoCD per AKS cluster, pointed at the acme-azure-blueprint-webapp-gitops repository, so a deployment is a merged pull request, not a kubectl command.

What it does

An ArgoCD Application names a Git repository, a path, a target revision and a destination namespace. ArgoCD renders the manifests (here with Helm), compares them with the live cluster and reports the difference. With automated sync it applies the difference itself; without it, a person presses Sync. Prune removes objects that left Git; self-heal reverts changes made outside Git.

How BuiltForProd uses it

The argocd unit installs the argo-cd Helm chart, version 9.5.22, into the argocd namespace on the system pool, and creates everything ArgoCD needs:

• Repository access through the acme-runner GitHub App. The unit reads the App ID, installation ID and private key from the CI platform vault kv-acme-eus2-auto-plat in acme-core-auto and stores them in ArgoCD's repository Secret. No deploy key or personal token is involved.
• One Application, blueprint-app, tracking main at blueprint-app/helm into the blueprint-app namespace, with the value files values.yaml, values-<stage>.yaml and ../envs/<stage>/values.yaml. It uses server-side apply, never creates the namespace (the app-namespace unit owns it), and ignores the ExternalSecret fields the operator's webhook fills in, so there is no permanent diff.
• Sync per stage from the stage file's argocd_auto_sync: automated with prune and self-heal in dev and staging; manual in prod, where a person syncs after the deploy pull request is merged.
• High availability in staging and prod (argocd_ha = true): two replicas of the server, application controller, repository server and ApplicationSet controller, a PodDisruptionBudget for each, and redis-ha in place of a single Redis. redis-ha needs three nodes, which is why those stages run three system nodes.
• Access at argocd.<stage>.internal.company.com, such as argocd.prod.internal.company.com, on the nginx-internal controller of application routing, which also writes the DNS record. The certificate comes from cert-manager's internal CA, and the host is reachable from the VPN and the runners only.
• The ClusterSecretStore azure-kv for the External Secrets Operator is created here, in its own state, once the operator's CRDs exist.

The other half of the loop is in acme-azure-blueprint-webapp-code. Its workflows never push to the GitOps repository: the gitops-pr action opens a pull request that sets image.repository and image.tag in envs/<stage>/values.yaml, signed in with a GitHub App installation token. Dev and staging pull requests auto-merge; the prod pull request, opened by promote-prod.yml behind the prod Environment's reviewers, is merged by a person. Rollback is a revert of that pull request.

Terms you will see

Term	Meaning
Application	The ArgoCD object tying a Git path to a cluster namespace.
Sync	Applying the rendered manifests to the cluster.
Prune	Deleting live objects that no longer exist in Git.
Self-heal	Reverting live changes that were not made through Git.
Target revision	The branch ArgoCD follows, here main.
Deploy pull request	The pull request a code workflow opens to change an image tag.

Where to read more

• Azure Web App Blueprint overview for the delivery chain end to end.
• GitOps for the model.
• Helm for the chart ArgoCD renders.
• GitHub Actions for the workflows that open the pull requests.