⚓ Argo CD マスターガイド: Hook Phaseの種類と完璧な活用法

6月 21, 2026

—

こんにちは！Kubernetes環境でGitOpsを実践していると、「アプリケーションがデプロイされる前にDBマイグレーションを先に実行できないか？」とか、「デプロイが完了した後にSlackに通知を送れないか？」といった悩みが生まれるものです。

これらの要件を完璧に解決してくれるのが、まさにArgo CD Resource Hooksです。本日は、これらのHookが実行されるタイミングであるPhase（段階）の種類と、実務での活用法を詳しく掘り下げていきます。🛠️

1. ❓ Argo CD Hookとは何ですか？

基本的にArgo CDは、Gitにあるマニフェストをクラスターに「適用(Apply)」する役割を担います。しかし、Hookを使用すると、同期(Sync)プロセス中の特定のタイミングで特定のリソースを実行するように制御できます。

主にJobやPodリソースにアノテーションを付けて使用し、デプロイのライフサイクルを細かく調整するために使われます。

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. ⚠️ 注意事項とヒント

冪等性(Idempotency)の維持: PreSync Jobなどは複数回実行される可能性があるため、実行結果が常に同じであるか、重複実行に安全である必要があります。
リソース名: Hookリソースにはnameの代わりにgenerateNameを使用することをお勧めします。これにより、同期ごとに一意の名前が生成され、衝突を防ぎます。
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マイグレーションやデプロイ自動通知は、実務で生産性を高める上で不可欠な要素です。

本日取り上げた内容を皆さんのプロジェクトに適用し、より安全でスマートなデプロイパイプラインを構築してみてください！🎯