🔄 ArgoCD Replace Feature Complete Guide: The Ultimate Move When Patch Fails

Jun 17, 2026

—

When operating Kubernetes and ArgoCD, you might occasionally encounter situations where you think, “This resource isn’t updating and keeps throwing errors, what’s going on?” At such times, the magical option that comes to our rescue is the Replace feature.

Today, we’ll delve deep into what ArgoCD’s Replace feature is, why it’s needed, and how to apply it in a real operational environment! 🚀

Hello! When operating Kubernetes infrastructure, resources that cannot be resolved with kubectl apply often appear. Typically, ArgoCD uses a Patch method, which maintains existing resources and only applies changes. However, in certain situations, it becomes necessary to completely swap out a resource for a new one.

This is where the Replace option comes in. From now on, I’ll tell you everything about this feature!

1. What is Replace? 🤔

Basically, when ArgoCD synchronizes (Sync) resources, it uses a method similar to kubectl apply. That is, it prefers the Strategic Merge Patch method, which subtly injects only the changed parts into existing resources.

However, when the Replace feature is enabled, ArgoCD operates as follows:

It compares the configuration of the existing resource with the new configuration.
For resources where a simple patch is not possible (e.g., changes to Immutable fields), it either completely replaces the existing resource or deletes and recreates it.

💡 To put it in perspective?

– Patch: Replacing only old tires with new ones.

– Replace: Swapping out the entire car for a new model.

2. Why is Replace needed? ⚠️

While it would be ideal to solve everything with patches, Kubernetes has

“Immutable Fields”

that, once set, cannot be changed.

Service Selector: The labels of pods that a service targets are often immutable during runtime.
Job Resource: To change the spec of an already running Job, it must be deleted and recreated.
Resource Capacity Exceeded: Sometimes, the size of the last-applied-configuration annotation becomes too large, causing a regular apply to fail. (Kubernetes resource capacity limit issue)

In such situations, the Replace=true option automates the hassle of manually deleting and reapplying resources.

3. Practical Code: How to Apply Replace 💻

There are two main ways to apply the Replace feature in ArgoCD.

① Apply to the entire Application (Sync Policy)

You can configure all resources belonging to a specific app to attempt the Replace method when synchronized.

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/my-repo/manifests.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: my-namespace
  syncPolicy:
    syncOptions:
      # Enables the Replace option for all resources within the app.
      - Replace=true

② Apply to specific resources only (Annotation)

Instead of applying to the entire app, you can also configure it individually for specific problematic YAML files. This method is safer and recommended.

YAML

apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    # Specifies to use the Replace method only when synchronizing this particular service resource.
    argocd.argoproj.io/sync-options: Replace=true
spec:
  selector:
    app: my-new-app # If this field is immutable and causes an error, Replace will fix it!
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9376

4. Replace vs Server-Side Apply ⚖️

Recently, the Server-Side Apply option is also frequently used in ArgoCD. It’s important to understand the differences between the two.


Category	Replace	Server-Side Apply

—	—	—
Operation Method	Overwrites or recreates existing resources	Server (K8s) directly manages field ownership
Main Purpose	Resolving immutable field modification issues	Managing large-scale manifests and preventing conflicts
Risk Level	Medium (potential downtime during deletion and recreation)	Low (latest K8s standard method)

—

5. Precautions: Checklist for Production Environments 🚨

The Replace feature is powerful, but indiscriminate use can be dangerous.

Downtime Occurrence: During the process of deleting and recreating resources, the service may be interrupted for a very short period. Be especially careful when replacing an entire Service or Deployment.
Data Loss: Incorrectly using it on data-containing resources like PersistentVolumeClaim (PVC) can lead to the loss of valuable data. (Absolutely be careful with data-related resources!)
Last Resort: Whenever possible, resolve structural issues first, and only use this feature when changes to Immutable fields are truly unavoidable.

6. Summary 🏁

Replace is a feature that forcibly replaces a resource when a regular patch (update) fails.
It can be configured via SyncOption=Replace=true.
It is excellent for resolving Immutable field changes or manifest size issues.
However, it must be used cautiously, always keeping in mind the potential for downtime and data loss.