Argo CD

Argo CD#

Argo CD is the GitOps continuous-delivery controller for Kubernetes. A controller in the cluster watches a Git repository of manifests and reconciles the cluster to match. The operator never kubectl apply to production; the operator commits and Argo CD applies. CNCF-graduated; the de-facto GitOps CD tool in 2026 alongside Flux.

Architecture#

  • Application (CRD), the binding between a Git source and a Kubernetes destination (cluster + namespace).

  • ApplicationSet (CRD), templates that generate Applications from inputs (cluster lists, Git directories, pull requests).

  • AppProject (CRD), an isolation boundary, source repos and destinations an Application may use.

  • Controller (the argocd-application-controller), the reconcile loop.

  • Repo-server, pulls Git repos and renders manifests (Helm, Kustomize, plain YAML, Jsonnet).

  • API server / UI / CLI, the operator surface.

A minimal Application#

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata: { name: web, namespace: argocd }
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/k8s-manifests
    targetRevision: main
    path: web/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: ["CreateNamespace=true"]

automated.prune deletes resources removed from Git; selfHeal reapplies the Git state if anything drifts.

CLI#

$ argocd login argocd.example.com
$ argocd app list
$ argocd app get web
$ argocd app sync web
$ argocd app rollback web <revision>
$ argocd app history web
$ argocd app diff web

Source layouts#

Argo CD’s repo-server renders manifests from one of:

  • Plain YAML, path points at a directory; the contents are applied.

  • Kustomize, path points at a directory with a kustomization.yaml; the rendered output is applied.

  • Helm, path points at a chart, with values in the Application or in an adjacent file.

  • Jsonnet / Plugins, custom render via a config-management plugin.

ApplicationSet#

A factory for Applications. Useful for multi-cluster / multi-environment rollouts.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata: { name: web-clusters, namespace: argocd }
spec:
  generators:
    - clusters: { selector: { matchLabels: { env: prod } } }
  template:
    metadata: { name: 'web-{{name}}' }
    spec:
      project: default
      source:
        repoURL: https://github.com/myorg/k8s-manifests
        path: web/overlays/{{metadata.labels.region}}
      destination:
        server: '{{server}}'
        namespace: prod

Argo Rollouts (companion)#

Argo Rollouts is a separate controller that replaces the standard Deployment with a Rollout CRD supporting canary and blue-green strategies. Pairs cleanly with Argo CD, traffic shifting, analysis steps, and pause-for-promotion gates that the operator can drive from a UI or CLI.

When to pick Argo CD#

  • GitOps as the deployment model; declarative state in Git is the source of truth.

  • Multi-cluster fan-out where one Argo CD instance manages many clusters.

  • The team values a strong UI for diff / sync / rollback.

When to pick something else#

  • Lighter, more automation-shaped GitOps, Flux. The two tools are near-peers; the difference is mostly UX preference.

  • Imperative deployments preferred, the operator wants explicit kubectl apply in a CI pipeline instead of a reconciler.

References#

Contents