Argo CD Sync Phases & Hooks Deep Dive | Real-World Examples & Demo

Argo CD's synchronization process is far more sophisticated than a simple, one-shot execution of kubectl apply. To run robust, production-grade GitOps pipelines, you must control when and how resources are applied, validated, and cleaned up. This guide explores the internal mechanics of Argo CD sync phases and hooks, details how they differ, and demonstrates how to implement them to orchestrate complex deployment workflows.

1. Re-evaluating the Sync Operation: State Reconciliation vs. Application Health

A synchronization operation in Argo CD reconciles the desired state declared in Git with the live state of the Kubernetes cluster. However, a common point of confusion in production environments is the distinction between a successful synchronization and a healthy application.

State Reconciliation

The sync process compares Git manifests with the live cluster state to detect and fix configuration drift. A successful sync means that all manifests defined in Git were successfully parsed, validated, and applied to the cluster without API errors.

Delivery Confirmation vs. Workload Health

• Sync Success: This only confirms that the Kubernetes API server accepted and created the resources. It does not mean the workloads are running or healthy.
• Application Health: This is an independent assessment of whether the pods are running and ready.

Real-World Example: If you deploy a Kubernetes Deployment manifest with 4 replicas, but the container image tag is mistyped, the sync operation will report Success because the Deployment object was successfully created in the cluster. However, the application health will report Degraded or Unhealthy because the pods are stuck in an ImagePullBackOff loop.

2. The Mental Model: Sync Phases as Lifecycle Milestones

To understand how Argo CD manages complex deployments, think of synchronization as an umbrella process divided into sequential, named execution stages called Sync Phases.

The Job Interview Analogy

When you say, "I cleared the job interview," you are using an umbrella term for a process that actually consisted of multiple distinct phases:

1. Decision Phase: Deciding to switch jobs.
2. Preparation Phase: Creating a learning roadmap.
3. Execution Phase: Studying, revising, and practicing.
4. Interview Phase: Appearing for the rounds and receiving the offer.

If any early phase fails (e.g., you do not prepare), you cannot successfully transition to the final phase.

Similarly, Argo CD breaks down a sync operation into four primary sequential phases:

3. What are Argo CD Hooks?

A Hook is a standard or custom Kubernetes resource (most commonly a Kubernetes Job) that Argo CD handles differently from normal reconciliation. Instead of continuously tracking and enforcing its state, Argo CD executes hooks as conditional, one-time logic at specific points in the sync lifecycle.

Why Use Hooks?

Standard GitOps tools apply all manifests simultaneously. Hooks allow you to run tasks that must happen before or after your main application workloads are applied. Common use cases include:

• Running database schema migrations before updating the application.
• Performing prerequisite cluster checks (e.g., verifying the Kubernetes version or node availability).
• Running smoke tests or integration tests after a deployment.
• Sending Slack notifications or collecting logs if a deployment fails.

4. Deep Dive into Hook Types & Real-World Use Cases

Argo CD provides six hook types. Four of these map directly to the sync phases, while two handle special lifecycle events.

1. PreSync

Executes before the main manifests in the Sync phase are applied.

• Primary Use Case: Database migrations, schema updates, or checking cluster-wide prerequisites.
• PreSync vs. Init Containers: While init containers delay the startup of a main container within a single pod, they cannot prevent other Kubernetes manifests (like Services, ConfigMaps, or other Deployments) from being applied to the cluster. A PreSync hook can block the entire deployment process if prerequisites are not met.

2. Sync

Executes during the synchronization phase, alongside standard manifests.

• Primary Use Case: Rarely used in production, as standard manifests handle this phase natively.

3. PostSync

Executes only after all manifests in the Sync phase have been successfully applied and have reached a healthy state.

• Primary Use Case: Running automated smoke tests, verifying external URL reachability, or triggering cache-warming scripts.

4. SyncFail

Executes only if the synchronization operation fails at any point in the lifecycle.

• Primary Use Case: Sending failure alerts to Slack/PagerDuty, triggering automated rollbacks, or collecting diagnostic logs from failing pods.

5. PostDelete

Executes after the parent Argo CD Application Custom Resource Definition (CRD) itself is deleted.

• Primary Use Case: Cleaning up external resources (e.g., cloud load balancers, database instances, or DNS records) created outside of Kubernetes.

6. Skip

Instructs Argo CD to skip the execution of a hook.

• Common Misconception: Many developers believe the Skip hook is used to prevent standard manifests (like a ConfigMap) from being applied. This is incorrect. The Skip hook is used exclusively to disable a hook itself (e.g., temporarily disabling a PreSync database migration during troubleshooting).

5. Hook Annotations & Deletion Policies

Argo CD identifies hooks and determines how to manage them using metadata annotations defined within the resource's YAML manifest.

Key Annotations

• argocd.argoproj.io/hook: Specifies the phase in which the hook should run.

  YAML

  Copy

  metadata:
    annotations:
      argocd.argoproj.io/hook: PreSync
  

• argocd.argoproj.io/hook-delete-policy: Controls when the hook resource (e.g., the completed Kubernetes Job) is cleaned up from the cluster.

  Policy	Behavior	Rationale
  HookSucceeded	Deletes the hook resource after it executes successfully.	Keeps the cluster clean of successful, one-off jobs.
  HookFailed	Deletes the hook resource only if it fails.	Rarely used; usually, you want failed jobs to persist for debugging.
  BeforeHookCreation	Deletes any existing hook resource of the same name before starting a new sync.	Prevents "resource already exists" errors on subsequent sync runs.

6. The Lifecycle Matrix: Phases vs. Hooks Comparison

7. Step-by-Step Execution Flows

Successful Sync Flow with PreSync and PostSync Hooks

Failed Sync Flow (Pre-Sync Failure)

8. Hands-On Demo Setup: Directory & Repository Structure

To demonstrate sync hooks in action, we use a two-tier application consisting of a backend service and a frontend service. The configuration manifests are separated into dedicated Git repositories to adhere to GitOps best practices.

Directory Layout

Manifest Implementations

Backend Pre-Sync Hook (pre-sync-hook.yaml)

This manifest defines a Kubernetes Job that simulates a database migration. It must run and complete successfully before the backend deployment is applied.

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-sync-db-migration
  namespace: app1-ns
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded,BeforeHookCreation
spec:
  template:
    spec:
      containers:
      - name: db-migrator
        image: alpine:latest
        command: ["/bin/sh", "-c"]
        args:
        - |
          echo "Running DB migrations..."
          sleep 5
          echo "Migration completed successfully."
      restartPolicy: Never

Frontend Post-Sync Hook (post-sync-hook.yaml)

This manifest defines a Kubernetes Job that runs after the frontend deployment is applied. It performs a smoke test to verify that the frontend service is reachable on port 80.

apiVersion: batch/v1
kind: Job
metadata:
  name: frontend-smoke-test
  namespace: app1-ns
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded,BeforeHookCreation
spec:
  template:
    spec:
      containers:
      - name: smoke-tester
        image: alpine:latest
        command: ["/bin/sh", "-c"]
        args:
        - |
          echo "Checking frontend service reachability..."
          # Attempt to connect to the frontend service on port 80
          wget -qO- http://frontend-svc.app1-ns.svc.cluster.local:80 || exit 1
          echo "Smoke test passed successfully!"
      restartPolicy: Never

9. Step-by-Step Demo Execution

Step 1: Create the Target Namespace

Create the namespace where the application resources will reside:

kubectl create namespace app1-ns

Step 2: Apply the Argo CD Applications

Apply the Argo CD Application manifests to register the backend and frontend configurations with Argo CD:

kubectl apply -f app1-backend-config/Argo/backend-application.yaml
kubectl apply -f app1-frontend-config/Argo/frontend-application.yaml

Step 3: Execute and Observe the Backend Pre-Sync Hook

1. Open the Argo CD UI and navigate to the app1-backend application.
2. Click Sync and then Synchronize.
3. Observe the UI:
   • Argo CD first creates the pre-sync-db-migration Job.
   • The Deployment and Service manifests remain in an unapplied state.
   • Once the Job pod transitions to Completed, Argo CD deletes the Job object (due to the HookSucceeded policy).
   • Argo CD then transitions to the Sync phase and applies the backend Deployment and Service.

Step 4: Execute and Observe the Frontend Post-Sync Hook

1. Navigate to the app1-frontend application in the Argo CD UI.
2. Click Sync and then Synchronize.
3. Observe the UI:
   • Argo CD immediately applies the frontend Deployment and Service manifests.
   • Once the frontend pods are running and healthy, Argo CD transitions to the PostSync phase.
   • The frontend-smoke-test Job is created.
   • The Job runs its script, successfully reaches the frontend service, and exits with code 0.
   • Argo CD deletes the Job and marks the entire synchronization operation as Successful.

10. Troubleshooting & Edge Cases: Demystifying the Skip Hook

During troubleshooting, you may want to bypass a hook without deleting its manifest from Git. This is where the Skip hook is used.

Applying the Skip Hook

To temporarily disable the frontend smoke test, update the annotations in post-sync-hook.yaml:

metadata:
  name: frontend-smoke-test
  namespace: app1-ns
  annotations:
    # Change hook type to Skip to bypass execution
    argocd.argoproj.io/hook: Skip

Behavior Verification

1. Commit and push the updated manifest to your Git repository.
2. In the Argo CD UI, click Refresh to force Argo CD to pull the latest commit.
3. Click Sync and then Synchronize.
4. Observe the UI:
   • The frontend application synchronizes immediately.
   • The frontend-smoke-test Job is ignored and does not run.

Summary and Key Takeaways

• Sync Success vs. App Health: A successful sync only means that the Kubernetes manifests were successfully applied to the cluster, not that the application pods are running without errors.
• Sync Phases: These are the sequential stages (PreSync, Sync, PostSync, SyncFail) that define where Argo CD is in its synchronization lifecycle.
• Sync Hooks: These are one-off Kubernetes resources (typically Jobs) executed during specific sync phases to run custom operational logic.
• PreSync Hooks: Ideal for database schema migrations and prerequisite checks. If a PreSync hook fails, the entire sync operation stops immediately.
• PostSync Hooks: Best used for post-deployment validation, such as running smoke tests or warming up caches.
• SyncFail Hooks: Executed only when a sync operation fails, making them ideal for sending alerts or collecting diagnostic logs.
• Hook Deletion Policies: Use HookSucceeded and BeforeHookCreation to automatically clean up completed hook resources and prevent naming conflicts on subsequent deployments.
• The Skip Hook: This hook type is used to temporarily disable a hook during troubleshooting, rather than skipping standard application manifests.