Argo CD Sync Explained: Desired State, Live State, and Diff

Desired State vs Live State

One of the core GitOps concepts in Argo CD is the difference between the desired state and the live state. The desired state is what is written in your Git repository – the manifests (Deployments, Services, ConfigMaps, and so on) in the path configured in the Argo CD application source section. These are the files you want your cluster to look like.

The live state is what is actually running inside the cluster. Argo CD retrieves this information from the Kubernetes API, which returns the current state of your Kubernetes resources.

The Argo CD controller continuously compares the desired state with the live state. When they differ, the application has configuration drift. Argo CD calculates a diff to show exactly what changed and marks the application as OutOfSync.

Creating an Application and Observing the Diff

Open your running Argo CD instance. If you do not have one, start Argo CD and wait for it to be ready. Copy your password and navigate to the Argo CD page. Your username is admin.

Press the New App button. Fill in the fields:

• Project: default
• Repository URL: https://github.com/argoproj/argocd-example-apps.git
• Revision: HEAD
• Path: guestbook
• Cluster URL: https://kubernetes.default.svc
• Namespace: default

These settings use Argo CD's default Guestbook application, which is maintained by the Argo CD project and is commonly used for demonstrations.

Press Create, then Sync. Argo CD processes the manifests and synchronizes them with your cluster.

Go to your cluster (using VS Code or a terminal). You will see one Guestbook pod running.

Now manually change the number of replicas from one to three:

kubectl scale deployment guestbook --replicas=3

The cluster now has three replicas, but the Git repository still defines one replica. Your desired state is one replica, while your live state is three replicas.

Check Argo CD. The application status changes to OutOfSync. Open the Diff view to see exactly what changed between the desired state (one replica) and the live state (three replicas).

Enabling Auto-Sync and Self-Heal

To make the live state always match the desired state, click Details, scroll down, and enable Auto-Sync and Self-Heal.

After a few moments, Argo CD automatically synchronizes the deployment back to the desired state stored in Git. The application status changes to Synced, and your cluster once again has only one running replica.