Applying Self-Healing for Drift Remediation

Enable the self-healing feature to automatically revert manual, unauthorized changes made directly to cluster resources back to the Git-defined state.

In this lesson, you will learn how to enable Argo CD’s self-healing feature to ensure your cluster state remains perfectly synchronized with your Git repository, even when manual changes are introduced.

Why Drift Happens

In a mature GitOps workflow, your Git repository is the "Single Source of Truth." However, Kubernetes allows cluster administrators to make "out-of-band" changes using kubectl edit or kubectl patch. While these commands are useful for emergency debugging, they create configuration drift—the cluster state no longer matches your declarative manifests in Git. Without a mechanism to catch these changes, your documentation becomes inaccurate and your deployments become unpredictable.

Enabling Automated Self-Healing

Argo CD constantly runs a reconciliation loop comparing the live state of your cluster with the desired state in Git. By default, it detects drift and marks the application as OutOfSync. To close the loop, we configure "Self-Healing." When enabled, Argo CD will detect a change made to a resource via kubectl and automatically overwrite it to match the version in Git.

To enable this, you must configure the syncPolicy within your Application manifest:

spec:
  syncPolicy:
    automated:
      selfHeal: true
      prune: true

How It Works in Practice

Once selfHeal is set to true, the behavior is immediate:

An engineer runs kubectl scale deployment my-app --replicas=10 manually, bypassing the CI/CD pipeline.
The Argo CD controller detects that the live replica count (10) differs from the Git manifest (e.g., 3).
Because self-healing is active, Argo CD triggers a sync operation automatically.
The deployment is reverted back to 3 replicas, effectively "healing" the drift within seconds.

This process removes the reliance on manual oversight to catch unauthorized changes. It forces the team to commit all changes to Git, ensuring that every modification is auditable, peer-reviewed, and repeatable. By letting the controller handle remediation, you eliminate the "configuration decay" that often plagues large-scale Kubernetes environments.

Key Takeaway: Enabling self-healing allows your GitOps controller to act as a security and consistency guardrail, automatically reverting any unauthorized manual changes to restore the cluster to your predefined Git state.