⚓ Argo CD 마스터 가이드: Hook Phase의 종류와 완벽 활용법

안녕하세요! Kubernetes 환경에서 GitOps를 실천하다 보면 "애플리케이션이 배포되기 전에 DB 마이그레이션을 먼저 실행할 수 없을까?" 또는 "배포가 끝난 뒤에 Slack으로 알림을 보낼 순 없을까?" 하는 고민이 생기기 마련입니다.

이러한 요구사항을 완벽하게 해결해 주는 것이 바로 Argo CD Resource Hooks입니다. 오늘은 이 Hook들이 실행되는 시점인 Phase(단계)의 종류와 실무 활용법을 상세히 파헤쳐 보겠습니다. 🛠️

 

---

1. ❓ Argo CD Hook이란 무엇인가요?

기본적으로 Argo CD는 Git에 있는 매니페스트를 클러스터에 '적용(Apply)'하는 역할을 합니다. 하지만 Hook을 사용하면 동기화(Sync) 과정 중 특정 시점에 특정 리소스를 실행하도록 제어할 수 있습니다.

주로 Job이나 Pod 리소스에 주석(Annotation)을 달아 사용하며, 배포의 생명 주기를 세밀하게 조정하는 데 사용됩니다.

---

2. ⏳ Hook Phase의 5가지 종류

Argo CD에는 총 5가지의 주요 Hook Phase가 있습니다. 각 단계는 동기화 프로세스의 특정 시점에 트리거됩니다.

① PreSync (동기화 전)

동기화 작업이 시작되기 전, 즉 실제 애플리케이션 리소스가 클러스터에 적용되기 전에 실행됩니다.

• 용도: 데이터베이스 스키마 마이그레이션, 설정 파일 사전 검증.
• 특징: 이 단계의 Hook이 성공해야만 다음 단계로 넘어갑니다. 실패 시 동기화는 중단됩니다.

② Sync (동기화 중)

애플리케이션 리소스가 적용되는 것과 동시에 실행됩니다.

• 용도: 복잡한 배포 오케스트레이션.
• 특징: 일반적인 리소스와 함께 생성됩니다.

③ PostSync (동기화 후)

모든 리소스가 성공적으로 배포되고 Healthy 상태가 된 후에 실행됩니다.

• 용도: 상태 검사(Health Check), 외부 서비스 알림(Slack/Teams), 부하 테스트 실행.

④ SyncFail (동기화 실패 시)

동기화 과정 중 에러가 발생하여 실패했을 때 트리거됩니다.

• 용도: 에러 로그 수집, 정리 작업, 실패 알림 전송.

⑤ Skip (건너뛰기)

Argo CD가 해당 리소스의 동기화를 건너뛰도록 지시합니다. (주로 디버깅 시 사용)

---

3. 💻 실전 코드: Hook 적용하기

Hook을 적용하려면 매니페스트의 metadata.annotations 섹션에 argocd.argoproj.io/hook을 추가해야 합니다.

📜 예시: DB 마이그레이션 (PreSync Job)

YAML

apiVersion: batch/v1
kind: Job
metadata:
  generateName: schema-migrate-
  annotations:
    # 1. Hook의 단계를 정의합니다. (동기화 전 실행) 🛡️
    argocd.argoproj.io/hook: PreSync
    # 2. Hook 실행 후 리소스 삭제 정책 설정 (성공 시 삭제) 🗑️
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: my-db-migrator:v1.0.0
        command: ["/app/migrate.sh"]
      restartPolicy: Never
  backoffLimit: 2

📜 예시: 배포 완료 알림 (PostSync Pod)

YAML

apiVersion: v1
kind: Pod
metadata:
  generateName: slack-notifier-
  annotations:
    # 모든 리소스가 정상 배포된 후 실행됩니다. 📢
    argocd.argoproj.io/hook: PostSync
    # 실행 완료 후 결과에 상관없이 5분 뒤 삭제
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  containers:
  - name: notify
    image: curlimages/curl
    command: ["curl", "-X", "POST", "-d", "payload={'text': '배포 완료!'}", "https://hooks.slack.com/..."]
  restartPolicy: Never

---

4. 🧹 Hook 삭제 정책 (hook-delete-policy)

Hook으로 생성된 리소스(주로 Job)를 언제 삭제할지도 매우 중요합니다. 삭제하지 않으면 클러스터에 완료된 Job들이 계속 쌓이게 됩니다.

정책 종류	설명
HookSucceeded	Hook이 성공적으로 종료되면 즉시 삭제 (가장 권장됨)
HookFailed	Hook이 실패했을 때만 삭제 (디버깅 시 불편할 수 있음)
BeforeHookCreation	새로운 Hook이 생성되기 직전에 이전 Hook을 삭제

---

5. ⚠️ 주의사항 및 팁

1. 멱등성(Idempotency) 유지: PreSync Job 등은 여러 번 실행될 수 있으므로, 실행 시 결과가 항상 동일하거나 중복 실행에 안전해야 합니다.
2. 리소스 이름: Hook 리소스는 name 대신 generateName을 사용하는 것이 좋습니다. 매 동기화마다 고유한 이름으로 생성되어 충돌을 방지합니다.
3. Sync Waves와의 결합: argocd.argoproj.io/sync-wave와 함께 사용하면 더 정교한 순서 제어가 가능합니다. (예: Wave 1에서 DB 배포, Wave 2의 PreSync에서 마이그레이션 실행)

---

📝 요약 테이블

Phase	실행 시점	주요 사용 사례
PreSync	리소스 배포 전	DB 마이그레이션, 사전 체크
Sync	리소스 배포와 동시	병행 작업 실행
PostSync	배포 완료(Healthy) 후	알림 전송, 통합 테스트
SyncFail	에러 발생 시	복구 스크립트, 실패 알림

---

💡 마치며

Argo CD의 Hook Phase를 이해하면 단순한 배포 도구를 넘어 강력한 Workflow 엔진으로 활용할 수 있습니다. 특히 DB 마이그레이션이나 배포 자동 알림은 실무에서 생산성을 높여주는 필수적인 요소입니다.

오늘 다룬 내용들을 여러분의 프로젝트에 적용해 보시고, 더 안전하고 스마트한 배포 파이프라인을 구축해 보세요! 🎯

---