Understanding Argo CD Sync Waves with Examples

Article Content

What Are Argo CD Sync Phases and Waves?

Argo CD is a continuous delivery tool that automates software deployments in Kubernetes. Sync phases and waves manage the order and timing of resource application. Sync phases define logical steps during an application deployment, such as pre-sync, sync, and post-sync. Each phase serves a specific purpose, facilitating sequencing and control over the deployment process.

Sync waves control resource deployment order within the phases. By specifying waves, users can control the sequence in which resources are applied to the cluster, enabling dependencies to be respected and ensuring that components are deployed in the correct order.

The Role of Sync Waves in the Argo CD GitOps Process

In the GitOps model used by Argo CD, sync waves play a crucial role in managing the order of resource deployment. When deploying complex applications with multiple interdependent components, it’s important to ensure that resources are applied in a specific sequence. 

Sync waves allow users to control this sequence by assigning a wave value to each resource, specifying when it should be applied within its sync phase. For instance, resources with a wave value of 0 will be processed before those with a wave value of 1. This helps in handling dependencies, such as creating a ConfigMap before a Deployment that relies on it, or ensuring that critical infrastructure is ready before application components are rolled out.

Sync waves also help optimize the stability and reliability of the GitOps process. By breaking the deployment into logical waves, Argo CD can introduce delays between waves, allowing external controllers or services time to react to changes before subsequent resources are applied. This reduces the likelihood of race conditions and minimizes deployment issues, especially in environments where certain resources need time to stabilize before others are introduced.

Read our guide to ArgoCD architecture

How Do Argo CD Sync Phases and Waves Work?

When Argo CD initiates a sync process, it follows a systematic approach to manage the deployment of resources. The process begins by organizing resources according to several criteria in a specific order:

  1. Phase: Resources are first grouped by the sync phase they belong to, such as pre-sync, sync, or post-sync.
  2. Wave: Within each phase, resources are ordered by their wave values. Lower wave values are prioritized for creation and updates, while higher wave values are prioritized for deletions.
  3. Kind: After organizing by wave, resources are further ordered by their Kubernetes kind. For example, namespaces are usually processed before other resources, followed by custom resources.
  4. Name: Finally, resources are sorted by name.

Once the resources are ordered, Argo CD determines the next wave to apply. It looks for the first wave containing any resources that are out-of-sync or unhealthy. Resources in that wave are then applied to the cluster.

This process is repeated until all resources across all phases and waves are in-sync and healthy. However, if an application has unhealthy resources in the initial waves, it may never reach a fully healthy state.

During resource pruning (the process of cleaning up resources that are no longer needed), Argo CD processes resources in reverse wave order—starting from the highest wave and moving down. If a resource fails to be pruned in a higher wave, resources in subsequent lower waves will not be processed.
To prevent premature health checks and ensure that other controllers have time to react to changes, there is a configurable delay between sync waves. By default, this delay is set to 2 seconds, but it can be adjusted using the ARGOCD_SYNC_WAVE_DELAY environment variable.

Dan Garfield
Dan Garfield
VP of Open Source, Octopus Deploy
Dan is a seasoned leader in the tech industry with a strong focus on open source initiatives. Currently serving as VP of Open Source at Octopus Deploy, contributing as an Argo maintainer, co-creator of Open GitOps, and leveraging extensive experience as a co-founder of Codefresh, now part of Octopus Deploy.

TIPS FROM THE EXPERT

  1. Remember that Sync waves are optional. You don’t need to use them unless you want to override the default deployment order. In most cases defaults will work just fine.
  2. Sync waves only work for individual resources within an Application. They do not work across different Argo CD applications. See this guide for achieving this scenario.
  3. Sync waves can work with and without Phases. Understand the difference of scope between the two approaches. We advise using either Phases for simple scenarios or just waves for most advanced cases.
  4. Specifically for database migrations instead of using Sync waves, we recommend a dedicated Database operator. See our guide here.
  5. If you find yourself using too many actions in the Post-Sync phases (running smoke tests, sending an alert, starting another workflow) then use sync-waves within that phase to specify the exact order of those actions.

ArgoCD Sync Waves Phases

Argo CD sync phases and waves provide structured control over deployment steps, using designated hooks to define specific actions at each phase of the sync process:

1. PreSync Phase:

Actions in this phase execute before the primary sync operation. These might include tasks such as preparing databases, creating specific infrastructure, or running initial configurations. 

Here is an example of a database migration job that uses PreSync:

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
    argocd.argoproj.io/sync-wave: "-1"
spec:
  template:
    spec:
      containers:
      - name: postgresql-client
        image: my-postgres-data:11.5
        command: ["psql", "-h=my_postgresql_db", "-U postgres", "-f preload.sql"]
      restartPolicy: Never

2. Sync Phase

This is the main phase, where most application components are deployed. Resources are organized by sync waves to control the order of application within this phase, ensuring dependencies are respected.

3. PostSync Phase

Actions in the PostSync phase execute after the primary sync operation is complete. This might involve cleanup tasks or notifications. 

For example, a Slack notification job could be configured here to alert users that the application sync succeeded:

apiVersion: batch/v1
kind: Job
metadata:
  generateName: app-slack-notification-
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: slack-notification
        image: curlimages/curl
        command:
        - "curl"
        - "-X"
        - "POST"
        - "--data-urlencode"
        - "payload={\"channel\": \"#somechannel\", \"text\": \"App Sync succeeded\"}"

4. SyncFail Phase

This phase defines actions that execute if the sync process fails, enabling automated responses to deployment issues.

Best Practices for Using Argo CD Sync Waves Effectively

When working with Argo CD sync waves, it’s important to follow certain best practices to ensure a smooth deployment process:

  1. Plan your waves carefully: Before setting up sync waves, map out the dependencies between your resources. Determine the sequence in which resources need to be deployed to avoid issues where a resource is applied before its dependencies are ready.
  2. Use negative waves for pre-deployment steps: If you have tasks that need to be completed before deploying any resources, assign them a negative wave value. This allows these tasks to be executed before the main sync process begins. For example, you might use a negative wave for tasks like setting up infrastructure or configuring environment variables that are required by the main application components.
  3. Use positive waves for post-deployment steps: Tasks that should only be executed after the main resources have been deployed should be assigned positive wave values. These might include cleanup activities, additional configuration, or triggering dependent services that rely on the successful deployment of earlier resources.
  4. Keep it simple: While sync waves are useful, overusing them can complicate your deployment process unnecessarily. Only use sync waves when there is a clear dependency that needs to be managed. Aim to keep your wave structure as straightforward as possible to reduce potential errors and simplify troubleshooting.

Codefresh: A Modern, Argo-Based CI/CD Platform

The Codefresh platform, powered by Argo, combines the best of the open-source with an enterprise-grade runtime allowing you to fully tap the power of Argo Workflows, Events, CD, and Rollouts. It provides teams with a unified GitOps experience to build, test, deploy, and scale their applications.

You can use Codefresh for your platform engineering initiative either as a developer portal or as the machinery that takes care of everything that happens in the developer portal. Your choice depends on how far your organization has adopted Kubernetes and micro-services

Codefresh is a next generation CI/CD platform designed for cloud-native applications, offering dynamic builds, progressive delivery, and much more.

Check It Out
Related Argo CD articles