🔄 ArgoCD Replace 기능 완벽 가이드: Patch가 안 될 때의 필살기

쿠버네티스와 ArgoCD를 운영하다 보면 간혹 "이 리소스는 업데이트가 안 되고 자꾸 에러가 나네?" 하는 상황을 마주하게 됩니다. 이때 우리를 구원해 줄 마법 같은 옵션이 바로 Replace 기능입니다.

오늘은 ArgoCD의 Replace 기능이 무엇인지, 왜 필요한지, 그리고 실제 운영 환경에서 어떻게 적용하는지 아주 깊이 있게 파헤쳐 보겠습니다! 🚀

안녕하세요! 쿠버네티스 인프라를 운영하다 보면 kubectl apply로는 해결되지 않는 리소스들이 종종 등장합니다. 보통 ArgoCD는 기존 리소스를 유지하면서 변경 사항만 반영하는 Patch 방식을 사용하지만, 특정 상황에서는 리소스를 아예 새로 갈아끼워야만 하는 경우가 있죠.

이때 사용하는 것이 바로 Replace 옵션입니다. 지금부터 이 기능의 모든 것을 알려드릴게요!

---

1. Replace란 무엇인가요? 🤔

기본적으로 ArgoCD는 리소스를 동기화(Sync)할 때 kubectl apply와 유사한 방식을 사용합니다. 즉, 기존 리소스에 변경된 부분만 슥~ 집어넣는 Strategic Merge Patch 방식을 선호하죠.

하지만 Replace 기능을 활성화하면, ArgoCD는 다음과 같이 동작합니다.

1. 기존 리소스의 설정과 새로운 설정을 대조합니다.
2. 단순한 패치가 불가능한 리소스(Immutable field 변경 등)의 경우, 기존 리소스를 통째로 교체(Replace) 하거나 삭제 후 재생성합니다.

💡 비유하자면?

• Patch: 낡은 타이어만 새 타이어로 교체하는 것.
• Replace: 차를 아예 새 모델로 바꾸는 것.

---

2. 왜 Replace가 필요한가요? ⚠️

모든 것을 패치로 해결할 수 있다면 좋겠지만, 쿠버네티스에는 **"한 번 정하면 못 바꾸는 필드(Immutable Fields)"**가 존재합니다.

• Service Selector: 서비스가 바라보는 파드의 레이블은 실행 중 변경이 불가능한 경우가 많습니다.
• Job 리소스: 이미 실행 중인 Job의 스펙을 변경하려면 반드시 삭제 후 재생성해야 합니다.
• 리소스 용량 초과: 가끔 last-applied-configuration 어노테이션의 크기가 너무 커져서 일반적인 apply가 실패할 때가 있습니다. (쿠버네티스 리소스 용량 제한 문제)

이런 상황에서 Replace=true 옵션은 수동으로 리소스를 지웠다 깔아야 하는 번거로움을 자동화해 줍니다.

---

3. 실전 코드: Replace 적용 방법 💻

ArgoCD에서 Replace 기능을 적용하는 방법은 크게 두 가지입니다.

① Application 전체에 적용하기 (Sync Policy)

특정 앱에 속한 모든 리소스가 동기화될 때 Replace 방식을 시도하도록 설정할 수 있습니다.

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:
      # 앱 내의 모든 리소스에 대해 Replace 옵션을 활성화합니다.
      - Replace=true 

② 특정 리소스에만 적용하기 (Annotation)

앱 전체가 아닌, 문제가 되는 특정 YAML 파일에만 개별적으로 설정할 수도 있습니다. 이 방법이 더 안전하고 권장됩니다.

YAML

apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    # 이 특정 서비스 리소스만 동기화할 때 Replace 방식을 사용하도록 지정합니다.
    argocd.argoproj.io/sync-options: Replace=true
spec:
  selector:
    app: my-new-app # 만약 이 필드가 수정 불가능해 에러가 난다면 Replace가 해결해줍니다!
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9376

---

4. Replace vs Server-Side Apply ⚖️

최근 ArgoCD에서는 Server-Side Apply 옵션도 많이 쓰입니다. 둘의 차이를 아는 것이 중요합니다.

구분	Replace	Server-Side Apply
작동 방식	기존 리소스를 덮어쓰거나 재생성	서버(K8s)가 직접 필드 소유권을 관리
주요 목적	불변(Immutable) 필드 수정 해결	대규모 매니페스트 관리 및 충돌 방지
위험도	중간 (삭제 후 재생성 시 다운타임 발생 가능)	낮음 (최신 K8s 표준 방식)

---

5. 주의사항: 운영 환경에서의 체크리스트 🚨

Replace 기능은 강력하지만, 무분별하게 사용하면 위험할 수 있습니다.

1. 다운타임 발생: 리소스를 삭제하고 다시 생성하는 과정에서 아주 짧은 순간 서비스가 중단될 수 있습니다. 특히 Service나 Deployment 전체를 Replace 할 때 주의하세요.
2. 데이터 유실: PersistentVolumeClaim(PVC)과 같이 데이터를 담고 있는 리소스에 잘못 사용했다가는 소중한 데이터가 날아갈 수 있습니다. (데이터 관련 리소스는 절대 주의!)
3. 최후의 수단: 가급적이면 구조적인 문제를 먼저 해결하고, 정말로 Immutable 필드 변경이 불가피한 경우에만 사용하세요.

---

6. 요약 🏁

• Replace는 일반적인 패치(Update)가 실패할 때 리소스를 강제로 교체하는 기능입니다.
• SyncOption=Replace=true를 통해 설정 가능합니다.
• Immutable 필드 변경이나 매니페스트 크기 문제를 해결하는 데 탁월합니다.
• 하지만 다운타임과 데이터 유실 가능성을 항상 염두에 두고 신중하게 사용해야 합니다.