Automate GitOps with ArgoCD

You've spent hours manually running kubectl apply -f and debugging drift between your Kubernetes cluster and your manifest repository. Every time an engineer merges a pull request, someone has to remember to update the deployment — and when they forget, your production environment silently diverges from what lives in Git. That disconnect is a recipe for outage fatigue, and it's the exact reason GitOps practitioners turn to ArgoCD. ArgoCD reconciles your cluster state against the manifests in Git, so your infrastructure always matches what's committed — no manual sync, no drift, no drama.

The Problem This Lesson Solves

Running a Kubernetes cluster without a GitOps loop is like flying a plane without an autopilot. You can keep it level manually, but one distraction leads to drift — and drift in production means downtime.

Common pain points before ArgoCD:

1. Manual syncing — engineers run kubectl apply from local machines, creating inconsistency.
2. Drift detection — no automatic way to know when a team member changed a Deployment behind your back.
3. Rollback chaos — reverting a bad push requires hunting for the last known-good manifest.
4. Audit nightmare — who changed what, when? Without a Git history, you're guessing.

ArgoCD solves all four by treating your Git repository as the single source of truth for cluster state.

Core Concept / Mental Model

Think of ArgoCD as a dedicated robot operator that watches your Git repo 24/7. Every time you push a commit that modifies a Kubernetes manifest, ArgoCD notices the change and automatically applies it to your cluster — if the actual cluster state doesn't match what's in Git, ArgoCD pulls it back in line.

Why "GitOps" and not just "CI/CD":

GitOps isn't just about deploying from a pipeline — it's about continuous reconciliation. Traditional CI/CD pushes once and walks away. ArgoCD constantly verifies that the cluster still matches the declared state. If someone runs kubectl delete deployment manually, ArgoCD recreates it within minutes.

Key concepts:

• Application — a logical grouping of Kubernetes resources (Deployments, Services, ConfigMaps) that ArgoCD manages as a unit.
• Sync — the operation of applying the desired state from Git to the cluster.
• Sync policy — how and when ArgoCD syncs: automatic, manual, or with prune (removing resources that no longer exist in Git).
• Health status — ArgoCD monitors the running state of resources, not just their presence.

This creates a closed-loop feedback system: developer pushes → Git webhook notifies ArgoCD → ArgoCD syncs cluster → health checks confirm success → developer sees status in UI or CLI.

How It Works Step by Step

Let's trace the flow from a developer's commit to a running application.

1. Developer commits a change to a Kubernetes manifest in a Git repository (e.g., changes replicas: 3 to replicas: 5).
2. Git webhook (or polling) triggers ArgoCD to check for differences.
3. ArgoCD compares the current cluster state against the manifest in Git (diff phase).
4. If out of sync, ArgoCD enforces the desired state by applying the manifest (kubectl apply equivalent).
5. ArgoCD monitors health — if the Deployment doesn't roll out successfully (e.g., image pull failure), ArgoCD reports it as "Degraded".
6. Sync status updates in the ArgoCD UI/CLI — green means synced and healthy, red means drift or failure.

Sync modes contrast:

Hands-On Walkthrough

Let's automate GitOps for a sample NGINX Deployment using ArgoCD.

Prerequisites:

• A running Kubernetes cluster (minikube or kind works)
• kubectl installed and configured
• ArgoCD installed in the cluster (quick install: kubectl create namespace argocd && kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml)

1. Prepare Your Git Repository

Create a public GitHub repo called argocd-demo and add the following manifest:

# argocd-demo/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80

Commit and push this file.

2. Create an ArgoCD Application

Use the ArgoCD CLI to create an application that points to your repo. First, log in:

# port-forward the ArgoCD server
kubectl port-forward svc/argocd-server -n argocd 8080:443 &

# get initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# login (default user: admin)
argocd login localhost:8080 --username admin --password <your-password>

Now create the Application:

argocd app create nginx-demo \
  --repo https://github.com/<your-username>/argocd-demo \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --sync-policy automated --auto-prune --self-heal

Explanation of flags: - --sync-policy automated — ArgoCD syncs automatically on commits. - --auto-prune — if you delete a resource from Git, ArgoCD removes it from the cluster. - --self-heal — if someone runs kubectl delete deployment manually, ArgoCD recreates it.

3. Observe the Sync

After a few seconds, check the application status:

argocd app get nginx-demo

Output should show:

Name:               argocd/nginx-demo
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          default
URL:                https://localhost:8080/applications/nginx-demo
Repo:               https://github.com/<your-username>/argocd-demo
Target:             HEAD
Path:               .
Sync Status:        Synced
Health Status:      Healthy

Pro tip: Open the ArgoCD UI at http://localhost:8080 (login with admin credentials) to see a visual dependency graph of your resources. It's much easier to spot drifts on the UI than on the command line.

4. Simulate a Change

Now modify replicas: 2 to replicas: 5 in your Git repo, commit, and push. Within seconds, ArgoCD syncs the change:

argocd app get nginx-demo
# replicas in cluster should now be 5
kubectl get pods -l app=nginx

You should see five pods running.

Compare Options / When to Choose What

ArgoCD is powerful, but it's not the only GitOps tool. Here's how it stacks up against alternatives:

When to choose ArgoCD: - You need a visual dashboard for operations teams. - You manage multiple clusters from a single control plane. - You already use Argo Workflows or other Argo projects.

When to reconsider: - Single cluster, small team — Flux might be simpler. - You want to avoid CRD overload in a minimal cluster.

Troubleshooting & Edge Cases

1. Application stuck in "Out of Sync" even after push

• Check the Git revision: argocd app get <app-name> shows the target revision. If it's not HEAD, ArgoCD may be pointing to a specific branch or tag.
• Ensure the webhook is configured (or rely on polling — default is 3 minutes). Force a refresh: argocd app sync <app-name>.

2. Auto-sync not triggering

• Verify that the sync policy is set to automated and prune/self-heal are not conflicting.
• Run argocd app set <app-name> --sync-policy automated to re-enable.

3. Resource created but stuck in "Progressing" health

• Common cause: the Deployment's progressDeadlineSeconds is set too low or the image doesn't exist.
• Check pod events: kubectl describe pod -l app=nginx — look for Failed to pull image or CrashLoopBackOff.

4. Pruning removes resources unexpectedly

Caution: --auto-prune deletes any resource that isn't in Git. If you have a ConfigMap that should be cluster-scoped but isn't tracked, ArgoCD will remove it. Always test with --dry-run first.

argocd app sync <app-name> --dry-run --prune

5. Manual change reverted

• If someone runs kubectl scale deployment nginx-demo --replicas=10, ArgoCD's self-heal will scale it back to 2 within minutes. To debug, check the ArgoCD logs:

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller | grep "nginx-demo"

What You Learned & What's Next

You now understand why manual kubectl apply creates drift risks, how ArgoCD's reconciliation loop works, and how to create an automated GitOps pipeline from a Git commit to a running application. You've seen the sync comparison table and know when to use ArgoCD over alternatives.

Key takeaways:

• Automate GitOps with ArgoCD means your cluster state is always declared in Git — never in someone's local shell.
• ArgoCD continuously reconciles: it detects drift and fixes it automatically.
• The three core ArgoCD resources are Application, Sync Policy, and Health Status.
• Auto-prune and self-heal are powerful but require testing with dry-run first.

Next topic in this track: Rollout Strategies with Argo Rollouts — you'll build on this GitOps foundation to implement canary and blue-green deployments with automated promotion and rollback.

Ready to level up? In the next lesson, you'll learn how to perform canary deployments with Argo Rollouts, integrate them with the GitOps flow you just set up, and automatically promote or rollback based on metrics.

Pro tip: Before moving on, practice changing a ConfigMap in your Git repo and watching ArgoCD re-deploy the pods automatically. Notice how it handles Secrets? That's coming in a future lesson.