Understanding GitOps Sync Loops with ArgoCD

Introduction

GitOps treats a Git repository as the single source of truth for infrastructure and application configuration. Changes are made by committing to Git — not by running kubectl apply directly. A GitOps operator running in the cluster continuously compares the desired state in Git with the actual state in the cluster and reconciles any differences. ArgoCD is the most widely adopted Kubernetes GitOps operator, providing a declarative, self-healing deployment model with a rich UI and RBAC.

Step-by-Step: How ArgoCD Works

flowchart TD
    A["1. Application Resource"]
    B["2. The Reconciliation Loop"]
    C["3. Detecting Drift (OutOfSync)"]
    D["4. Progressive Delivery with Rollouts"]
    E["5. ApplicationSets for Multi-Cluster Deployments"]
    A --> B
    B --> C
    C --> D
    D --> E

Step 1: Application Resource

An ArgoCD Application defines what to sync and where to sync it:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/k8s-config.git
    targetRevision: main    # Git branch/tag/commit
    path: apps/my-api/overlays/production  # Kustomize overlay path
  destination:
    server: https://kubernetes.default.svc  # Same cluster
    namespace: production
  syncPolicy:
    automated:
      prune: true        # Delete resources removed from Git
      selfHeal: true     # Revert manual kubectl changes
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

Step 2: The Reconciliation Loop

ArgoCD runs a controller loop (default: every 3 minutes, configurable):

1. Fetch Git repo at targetRevision
2. Render manifests (Helm chart / Kustomize / raw YAML)
3. Compare rendered manifests with live Kubernetes resources
4. Compute diff (what's missing, what's extra, what's changed)
5. If diff exists AND sync is automated:
   → Apply changes to cluster (kubectl apply semantics)
   → Prune removed resources if prune=true
6. Update Application status: Synced/OutOfSync/Degraded

Step 3: Detecting Drift (OutOfSync)

# Check application sync status
argocd app get my-api

# Example output when drift detected:
Name:               my-api
Status:             OutOfSync
Sync:               OutOfSync (1 resource out of sync)

RESOURCE          KIND        STATUS        REASON
my-api            Deployment  OutOfSync     spec.replicas: 3 → 5 (manual kubectl scale)

# Manual sync with diff preview
argocd app diff my-api
argocd app sync my-api --dry-run
argocd app sync my-api

Step 4: Progressive Delivery with Rollouts

Integrate with Argo Rollouts for canary/blue-green without Flagger:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-api
spec:
  replicas: 10
  strategy:
    canary:
      steps:
      - setWeight: 10    # Send 10% traffic to canary
      - pause: {}        # Wait for manual promotion
      - setWeight: 50    # 50% to canary
      - pause:
          duration: 10m  # Auto-promote after 10 min if healthy
      - setWeight: 100
  selector:
    matchLabels:
      app: my-api
  template:
    metadata:
      labels:
        app: my-api
    spec:
      containers:
      - name: my-api
        image: registry.example.com/my-api:v2.0.0

Step 5: ApplicationSets for Multi-Cluster Deployments

# Deploy to all clusters matching labels
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-api-all-clusters
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
  template:
    metadata:
      name: '{{name}}-my-api'
    spec:
      source:
        repoURL: https://github.com/myorg/k8s-config.git
        targetRevision: main
        path: 'apps/my-api/overlays/{{metadata.labels.region}}'
      destination:
        server: '{{server}}'
        namespace: production

Key Takeaways

• ArgoCD continuously reconciles live cluster state with Git — manual kubectl changes are automatically reverted when selfHeal: true.
• The ArgoCD Application resource is the unit of GitOps deployment — it defines source (Git), destination (cluster/namespace), and sync policy.
• OutOfSync status triggers automated reconciliation; manual drift is detected within the polling interval (default 3 minutes).
• ApplicationSets enable one GitOps template to generate Application CRs for dozens of clusters or environments.
• GitOps requires a Git PR/merge workflow for all changes — direct cluster access for writes should be removed (use ArgoCD’s RBAC instead).