Choose How ArgoCD Tracks Kubernetes Resources (2026)

Argo CD doesn’t actually track Kubernetes resources directly; it tracks Git commits and then tells Kubernetes what it should look like.

Let’s see this in action. Imagine you have a Kubernetes deployment defined in deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app-container
        image: nginx:1.21.0

And this file is committed to a Git repository at a specific commit hash, say a1b2c3d4e5f6. Argo CD, configured to watch this Git repository and this specific path, sees that commit. Argo CD then takes the deployment.yaml from that commit and applies it to your Kubernetes cluster. If the cluster’s current state for my-app deployment doesn’t match what’s in deployment.yaml (e.g., it has 1 replica instead of 3), Argo CD will reconcile the difference.

The core of Argo CD’s tracking mechanism is its Application CRD. When you create an Argo CD Application, you define:

• Source: Where to find your desired state. This is typically a Git repository URL, a specific branch, and a path within that repo. You can also specify a target revision (like a commit hash or tag).
• Destination: The Kubernetes cluster and namespace where the desired state should be applied.
• Sync Policy: How Argo CD should keep the cluster in sync with the source. This can be automatic or manual.

Here’s a simplified Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-application
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/my-org/my-app-config.git
    targetRevision: HEAD # Or a specific commit hash like a1b2c3d4e5f6
    path: deployments/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

In this example, Argo CD will:

1. Monitor https://github.com/my-org/my-app-config.git.
2. Look at the deployments/production directory.
3. When a new commit is detected on the HEAD (main/master branch), it will take all the Kubernetes manifests found in that directory.
4. Apply those manifests to the production namespace on the cluster defined by https://kubernetes.default.svc.
5. If the cluster state drifts (e.g., someone manually scales down the deployment), selfHeal: true will cause Argo CD to reapply the desired state.
6. If a resource is removed from Git, prune: true will cause Argo CD to delete it from the cluster.

Argo CD uses a combination of Git polling and Kubernetes event watching. It periodically polls your Git repository for changes. Once a change is detected (a new commit), it fetches the manifests. Then, it compares these desired manifests against the live state in your Kubernetes cluster. If there’s a difference, it calculates the necessary Kubernetes API calls (create, update, delete) to make the cluster match the Git state. This comparison is often referred to as the "diff" or "sync" operation.

The key takeaway is that Argo CD’s "tracking" is a declarative reconciliation loop. You declare what you want in Git, and Argo CD continuously works to make what is in Kubernetes match what you want. It’s not about watching individual Kubernetes resource events for changes; it’s about watching Git for changes to your desired state and then enforcing that state on Kubernetes.

What most people don’t realize is that Argo CD can also track Helm charts and Kustomize overlays directly, without requiring you to generate raw YAML. When you specify helm or kustomize as the type in your source spec, Argo CD understands how to process those formats, fetch their dependencies, and render the final Kubernetes manifests before applying them. This means you can store your Helm Chart.yaml, values.yaml or Kustomize kustomization.yaml in Git, and Argo CD will handle the build process.

The next logical step after mastering basic tracking is understanding how to manage multiple applications and environments using Argo CD Projects and AppSets.