ArgoCD Tutorial: GitOps for Kubernetes

What is ArgoCD?

ArgoCD is a GitOps continuous-delivery tool for Kubernetes. You declare your desired state (manifests, Helm charts, or Kustomize) in Git, and ArgoCD continuously reconciles the cluster to match - with a dashboard showing what's in sync and what's drifted.

The key difference from a classic CI/CD pipeline is the direction of the flow. In a push-based pipeline, a CI job runs kubectl apply against the cluster, so the CI system needs cluster credentials and nothing checks the cluster afterwards. With ArgoCD, an agent running inside the cluster pulls from Git. The cluster credentials never leave the cluster, and ArgoCD keeps comparing the live state with Git long after the deploy is finished.

ArgoCD is a graduated CNCF project and one of the two most widely used GitOps tools, together with Flux.

How ArgoCD works (key concepts)

A few concepts cover most of what you will use:

• Application - the main custom resource. It connects a source (a Git repo, a path inside it, and a revision such as a branch or tag) to a destination (a cluster and a namespace).
• Sync status - whether the live cluster matches Git. Synced means they match; OutOfSync means something in Git or in the cluster has changed.
• Health status - whether the deployed resources are working, for example Healthy, Progressing, or Degraded. A Deployment is healthy when its pods are ready.
• Sync - the action of applying the Git state to the cluster. You can sync manually from the UI or CLI, or turn on automated sync.
• Project - a group of Applications with shared rules: which repos they may use, which clusters and namespaces they may deploy to. The built-in project is called default.

Installing ArgoCD

ArgoCD runs in its own namespace. Install it from the official manifests:

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Server-side apply is used here because some ArgoCD CRDs are too large for a standard client-side kubectl apply. Wait for the pods to become ready:

kubectl get pods -n argocd

To open the web UI locally, forward the API server port, then browse to https://localhost:8080:

kubectl port-forward svc/argocd-server -n argocd 8080:443

The user name is admin. The initial password is generated during install. Install the argocd CLI (for example brew install argocd, or download it from the ArgoCD releases page) and read the password with:

argocd admin initial-password -n argocd

Change this password after your first login, and delete the argocd-initial-admin-secret Secret once you no longer need it.

Your first Application

Here is a declarative Application that deploys the manifests in the manifests folder of a Git repo into a demo namespace. Replace repoURL with your own repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your/repo
    path: manifests
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply it to the cluster where ArgoCD runs:

kubectl apply -f demo-app.yaml

What each part of syncPolicy does:

• automated - ArgoCD syncs on its own when Git changes, instead of waiting for you to click Sync.
• prune: true - if you delete a manifest from Git, ArgoCD deletes the matching resource from the cluster.
• selfHeal: true - any manual drift in the cluster is reverted to match Git automatically.
• CreateNamespace=true - ArgoCD creates the demo namespace if it does not exist yet.

You can also create and manage Applications with the CLI. Log in first (argocd login localhost:8080), then:

# Create an Application from the public example repo
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# Sync it (needed because this one has no automated sync policy)
argocd app sync guestbook

# Check sync and health status
argocd app get guestbook
argocd app list

Changing and rolling back an app

With GitOps, the normal way to change an app is a commit. Edit a manifest in your repo - for example, raise replicas from 1 to 3 - and push. ArgoCD checks the repo every few minutes by default (you can also configure a Git webhook so it reacts right away). With automated sync on, the new replica count is applied and the Application returns to Synced.

To roll back, revert the commit in Git. ArgoCD sees the older state as the new desired state and applies it. Because the history of every change is in Git, you can always see who changed what, and when.

If something does not sync, argocd app get <name> and the UI show the error for each resource, and argocd app diff <name> shows exactly how the live state differs from Git.

When to use ArgoCD

Use ArgoCD when you want Git to be the single record of what runs in your clusters and you want a clear visual view of it. The web UI shows every Application, its resources, and its sync and health status, which makes it easy for a whole team - not only the people who know kubectl well - to see what is deployed. It works well for managing many apps across many clusters, and its Projects, RBAC, and SSO support fit shared platforms used by several teams.

ArgoCD is less useful for a short-lived test cluster where a plain kubectl apply is enough, or for teams that prefer a lighter, CLI-only setup made of small controllers - that is the approach Flux takes. For most teams that want GitOps with a strong UI, ArgoCD is a safe and popular choice.