GitOps the Hard Way, with Argo CD

Overwriting Resources Instead of Merging Into Them

The Replace option changes how Argo CD pushes your manifests into the cluster.

By default, Argo CD updates resources the same way kubectl apply does. apply is "smart": it compares three things:

1 - The manifest in your Git repository.
2 - The live resource in the cluster.
3 - The last version Argo CD applied.

It then changes only the fields that actually differ and leaves everything else alone. This is called a three-way merge. It is what you want most of the time, because other controllers and the cluster itself add fields to your resources, and a merge keeps those untouched.

But some fields cannot be changed once a resource is created. These are immutable fields. A common example is the selector of a Deployment, or certain fields on a Service. If your Git manifest changes one of these, apply cannot merge the change in (the API server rejects it) and the Application gets stuck out of sync.

Setting Replace=true tells Argo CD to use kubectl replace instead of kubectl apply. replace does not merge. It deletes the live resource's spec and writes yours in its place (and falls back to kubectl create if the resource does not exist yet). That gets you past the immutable-field problem, because you are not editing the field, you are recreating the whole resource definition.

The cost: replace discards any fields other controllers added to the resource, because it overwrites instead of merging. Turn it on deliberately, and prefer scoping it to the one resource that needs it with the argocd.argoproj.io/sync-options: Replace=true annotation rather than the whole Application.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: todo-app
  namespace: argocd
spec:
  destination