Skip to main content

ArgoCD

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

What it does​

An ArgoCD Application names a Git repository, a path and 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 in acme-aws-blueprint-webapp-infra installs the argo-cd Helm chart (version 9.5.22) into the argocd namespace and creates everything ArgoCD needs:

  • Repository access through the existing acme-runner GitHub App. A lead writes the App id, installation id and private key as parameters under /acme/usw2/<stage>/argocd/ in each stage account, and an ExternalSecret the module creates has the External Secrets Operator write them into ArgoCD's repository Secret. OpenTofu never reads the key, and no deploy key or personal token is involved.
  • One Application, blueprint-app, tracking main, path blueprint-app/helm, with value files layered values.yaml, values-<stage>.yaml, ../envs/<stage>/values.yaml. It uses server-side apply and ignores the fields the External Secrets Operator rewrites on an ExternalSecret.
  • Sync policy per stage from the stage stack file: dev and staging have automated sync with prune and self-heal; prod has argocd_auto_sync = false and needs a manual sync after the deploy pull request is merged.
  • High availability in staging and prod (argocd_ha = true): two replicas of the controller, server, repo server and ApplicationSet controller, a PodDisruptionBudget each, and the chart's redis-ha in place of a single Redis. This is why those stages run three nodes.
  • Access at argocd.<internal domain>, such as argocd.dev.internal.company.com, over the VPN. The server runs as a ClusterIP service with --insecure, behind an internal Application Load Balancer that the AWS Load Balancer Controller builds from the chart's Ingress: HTTPS on 443 with the stage's internal ACM certificate, the internal-tools Ingress group, and inbound restricted to the private address ranges. The internal ExternalDNS release writes the record.
  • The ClusterSecretStore objects aws-ssm (Parameter Store) and aws-secretsmanager (Secrets Manager) for the External Secrets Operator are also created here, so they exist in their own state after the operator's CRDs are ready.
  • Release records of the argo-cd and argocd-apps Helm releases are ConfigMaps (helm_driver = "configmap"), so the read-only plan role never reads a Kubernetes Secret.

The other half of the loop is in acme-aws-blueprint-webapp-code. Its workflows never push to the GitOps repository; each opens a pull request that sets image.repository and image.tag in envs/<stage>/values.yaml. Dev and staging pull requests auto-merge; the prod pull request is merged by a person. ArgoCD then syncs. Rollback is a revert of that pull request.

Terms you will see​

TermMeaning
ApplicationThe ArgoCD object tying a Git path to a cluster namespace.
SyncApplying the rendered manifests to the cluster.
PruneDeleting live objects that no longer exist in Git.
Self-healReverting live changes that were not made through Git.
Target revisionThe branch or tag ArgoCD follows, here main.

Where to read more​