🚀 ArgoCD 마스터 가이드: Hard Refresh의 비밀과 캐시 메커니즘 완벽 분석

안녕하세요! 인프라 운영과 배포 자동화의 핵심 도구인 ArgoCD를 사용하다 보면, Git에 분명히 수정 사항을 반영했는데 ArgoCD UI에는 "OutOfSync"가 뜨지 않거나, 반영이 느려서 답답했던 경험이 있으실 겁니다. 😅

오늘은 ArgoCD의 성능을 최적화하는 캐시(Cache) 시스템과, 이를 강제로 갱신하여 정합성을 맞추는 Hard Refresh에 대해 심층적으로 알아보겠습니다.

---

🔍 1. 왜 그냥 'Refresh'가 아니라 'Hard Refresh'인가요?

ArgoCD는 효율적인 리소스 관리를 위해 여러 단계의 캐싱 전략을 사용합니다. 일반적인 Refresh와 Hard Refresh의 차이를 이해하는 것이 핵심입니다.

✅ Soft Refresh (일반 리프레시)

• 작동 방식: ArgoCD가 이미 가지고 있는 Git 리포지토리의 캐시 데이터를 바탕으로 클러스터의 상태와 비교합니다.
• 사용 시점: 클러스터에 수동으로 변경된 사항이 있는지 확인할 때 유용합니다.
• 한계: Git 리포지토리에 새로운 커밋이 올라왔지만, ArgoCD가 아직 인지하지 못한 상태라면 일반 Refresh로는 해결되지 않습니다.

🔥 Hard Refresh (하드 리프레시)

• 작동 방식: 기존에 저장된 Git 매니페스트 캐시를 완전히 삭제하고, Git 리포지토리에서 데이터를 다시 긁어옵니다(Refetch). 그 후 Helm 차트나 Kustomize 템플릿을 다시 렌더링하여 클러스터 상태와 비교합니다.
• 사용 시점: Git의 최신 커밋이 반영되지 않을 때, Helm Chart의 의존성 문제가 있을 때, 혹은 매니페스트 생성 로직이 꼬였을 때 사용합니다.

---

⚙️ 2. ArgoCD의 캐시 메커니즘 이해하기

ArgoCD가 왜 Hard Refresh를 필요로 하는지 알기 위해서는 내부 구조를 조금 들여다봐야 합니다. 🧐

1. Repo Server: Git 리포지토리를 복제하고 helm template이나 kustomize build 명령어를 실행하여 최종 YAML을 생성합니다. 이 결과물은 메모리나 Redis에 캐싱됩니다.
2. Application Controller: 클러스터의 실제 상태(Live State)와 Repo Server가 만든 희망 상태(Desired State)를 비교합니다.
3. Timeout 설정: 기본적으로 ArgoCD는 3분(timeout.reconciliation)마다 Git을 체크합니다. 이 시간 차이 때문에 사용자는 "왜 바로 안 바뀌지?"라고 느낄 수 있습니다.

---

💻 3. 커맨드 라인(CLI)으로 Hard Refresh 실행하기

UI에서 버튼을 클릭하는 것도 방법이지만, 자동화 스크립트나 터미널 작업 시에는 CLI가 훨씬 강력합니다.

🛠️ 기본 명령어

ArgoCD CLI가 설치되어 있고 로그인이 완료된 상태여야 합니다.

Bash

 

# 특정 애플리케이션을 Hard Refresh 하기
argocd app get <APP_NAME> --hard-refresh

🐍 Python 스크립트를 이용한 자동화 예시

여러 개의 앱을 한꺼번에 Hard Refresh 해야 하거나, 배포 파이프라인(CI) 끝단에 넣고 싶을 때 유용합니다.

Python

 

import subprocess
import json

def hard_refresh_app(app_name):
    """
    특정 ArgoCD 애플리케이션에 대해 Hard Refresh를 수행하는 함수
    """
    print(f"🔄 '{app_name}' 애플리케이션 하드 리프레시 시작...")
    
    try:
        # --hard-refresh 옵션을 사용하여 앱 정보를 가져오면 갱신이 트리거됩니다.
        result = subprocess.run(
            ["argocd", "app", "get", app_name, "--hard-refresh"],
            capture_output=True,
            text=True,
            check=True
        )
        print(f"✅ '{app_name}' 갱신 성공!")
        
    except subprocess.CalledProcessError as e:
        print(f"❌ 에러 발생: {e.stderr}")

# 실행 예시
if __name__ == "__main__":
    target_app = "my-kubernetes-service"
    hard_refresh_app(target_app)

---

📦 4. 캐시 관련 고급 설정 (Controller & Repo Server)

만약 Hard Refresh를 너무 자주 눌러야 한다면, 시스템 설정 자체를 조정해 보는 것이 좋습니다. argocd-cm (ConfigMap)을 수정하여 캐시 유지 시간을 조정할 수 있습니다. 🛠️

argocd-cm 수정

캐시 보존 기간을 줄이면 더 자주 Git을 확인하지만, 서버 부하가 늘어날 수 있습니다.

YAML

 

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # Git 스캔 주기를 설정 (기본 3분)
  timeout.reconciliation: "180s"
  # 리포지토리 서버의 캐시 유효 기간 설정
  repo.cache.expiration: "24h"

---

💡 5. 요약 및 베스트 프랙티스

1. 언제 사용하는가? 🤔
   • Git 커밋은 확인되는데 ArgoCD UI에 반영이 안 될 때.
   • values.yaml 변경 후 Helm 템플릿 결과가 이전 버전일 때.
   • Webhook이 제대로 작동하지 않아 수동 갱신이 필요할 때.
2. 주의사항 ⚠️
   • 너무 빈번한 Hard Refresh는 Git Server(GitHub, GitLab 등)에 부하를 줄 수 있으며, API Rate Limit에 걸릴 위험이 있습니다.
   • 가급적 Webhook을 설정하여 Git Push 시 ArgoCD가 즉시 알 수 있도록 구성하는 것이 가장 우아한 방법입니다.

---

📝 마치며

ArgoCD의 Hard Refresh는 단순한 '새로고침' 그 이상의 의미를 갖습니다. 캐시의 늪에 빠져 "왜 배포가 안 되지?"라며 머리를 싸매고 계셨던 분들에게 이 포스팅이 작은 빛이 되었기를 바랍니다. ✨

더 궁금하신 점이나 본인만의 ArgoCD 꿀팁이 있다면 댓글로 공유해 주세요! 👇