ArgoCD — K8s SRE Reference

TL;DR

ArgoCD continuously compares desired state in Git with live cluster state. Healthy + Synced means live resources match Git and pass health checks. Find the owning Application before changing workloads — patch Git, not the cluster.

Mental Model

Concept	Meaning
Application	Maps a Git source to a Kubernetes destination
AppProject	RBAC boundary — which repos, clusters, and namespaces an app can use
Sync	Apply Git-rendered manifests to the cluster
Health	ArgoCD's readiness interpretation per resource type
Drift	Live state differs from Git-rendered desired state

Sync & Health Status

Status	Meaning	First check
Synced / Healthy	Git matches cluster; resources ready	No action needed
OutOfSync	Live differs from Git	`argocd app diff`
Degraded	Resource exists but unhealthy	`kubectl describe` the failing resource
Missing	Expected resource not in cluster	Check prune history or manual deletion
Unknown	Health cannot be determined	Check CRD missing or custom resource type
ComparisonError	Cannot render or compare Git source	Repo creds, Helm/Kustomize render error

Application YAML

This is the core ArgoCD object: it tells ArgoCD which Git path to render and which cluster/namespace should receive the result. Use this as the starting point when onboarding one app or one environment into GitOps.

yaml application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-api
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io  # Ensures cascade delete on app removal.
spec:
  project: platform
  source:
    repoURL: https://github.com/example/platform-apps.git
    targetRevision: main
    path: apps/web-api/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

AppProject

An AppProject is the guardrail around Applications. Use it to restrict which Git repos, clusters, namespaces, and Kubernetes resource types a team can deploy through ArgoCD.

yaml appproject.yaml

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform
  namespace: argocd
spec:
  sourceRepos:
    - https://github.com/example/platform-apps.git
  destinations:
    - namespace: app
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: "*"
      kind: "*"
  namespaceResourceWhitelist:
    - group: apps
      kind: Deployment

Helm Source

This fragment shows how an ArgoCD Application renders a Helm chart and applies environment-specific values. Use it when ArgoCD owns the release lifecycle but Helm still provides the app packaging.

yaml helm-application.yaml

source:
  repoURL: https://github.com/example/platform-apps.git
  targetRevision: main
  path: charts/web-api
  helm:
    valueFiles:
      - values-prod.yaml
    parameters:
      - name: image.tag
        value: "abc123f"   # Prefer Git commits over UI parameter edits.

Kustomize Source

This source points ArgoCD at a Kustomize overlay. Use it when the repo has a shared base and separate overlays for dev, staging, prod, or client-specific environments.

yaml kustomize-application.yaml

source:
  repoURL: https://github.com/example/platform-apps.git
  targetRevision: main
  path: apps/web-api/overlays/prod   # Must contain kustomization.yaml.

ignoreDifferences

Suppress known drift fields — common for HPA-managed replicas or mutating webhooks that add annotations.

yaml ignore-differences.yaml

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas          # HPA manages replica count.
    - group: autoscaling
      kind: HorizontalPodAutoscaler
      jqPathExpressions:
        - .status.currentReplicas

CLI & kubectl

Use these commands during incidents to find the owning Application, compare Git against live state, and inspect sync health before editing resources manually.

bash argocd-checks.sh

kubectl get applications -n argocd
kubectl describe application web-api -n argocd
kubectl logs -n argocd deploy/argocd-application-controller --tail=100

argocd app get web-api
argocd app diff web-api
argocd app sync web-api --prune
argocd app history web-api
argocd app rollback web-api <history-id>

Safe Client Workflow

Find the owning Application: kubectl get applications -A | grep <app>
Patch Git/Helm values/Kustomize overlays — not live resources unless incident process allows it.
Review argocd app diff before sync.
Watch rollout, events, and metrics after sync.
Rollback via Git revert or argocd app rollback per client policy.

Gotchas

!selfHeal reverts kubectl edits — expected behavior; fix Git instead.
!Helm hooks may not run the same way as direct helm upgrade — test hook behavior explicitly.
!Do not helm upgrade an ArgoCD-managed release unless emergency process allows it.
!Prune deletes resources removed from Git — review diffs carefully in prod.