Sync Policies

Automated sync policy allows Argo CD to apply changes from the Git repository automatically to the cluster. It can be configured in two modes: Auto-sync, wherein Argo CD automatically applies any changes as soon as they are detected in the Git repository, and Prune, wherein Argo CD automatically deletes resources that are not present in the Git repository but exist in the cluster.

Argo CD provides a variety of sync options to customize the synchronization process. For instance, setting Prune=false prevents an object from being pruned, ensuring it remains in the cluster even if it's not in the Git repository. On the other hand, Validate=false applies objects with the --validate=false flag, which can be useful for certain classes of objects that don't require validation.

Other options handle missing resources and resource deletion. The

SkipDryRunOnMissingResource=true

option skips the dry run for missing resource types, and Delete=false retains certain resources even after your application is deleted.

Argo CD also offers options to control the timing and method of resource application. The PruneLast=true option allows resource pruning to happen as a final, implicit wave of a sync operation – after the other resources have been deployed and become healthy. If a resource spec is too big for kubectl apply, the Replace=true option uses the kubectl replace or kubectl create command to apply changes.

Finally, Argo CD also provides options to manage out-of-sync resources and resource propagation. With the

ApplyOutOfSyncOnly=true

option, Argo CD syncs only out-of-sync resources, reducing pressure on the API server for applications with many objects. The PrunePropagationPolicy option controls the propagation policy for extraneous resources, with supported policies, including background, foreground, and orphan.

How do they work? When PrunePropagationPolicy is set to background, the Kubernetes garbage collector deletes the owner objects immediately, and the ownership-controlled objects are deleted in the background. For example, if you have a deployment that creates pods, and you delete the deployment with a background propagation policy, the deployment will be deleted immediately and the pods will be deleted in the background. You can set it as follows:

metadata:
  annotations:
    argocd.argoproj.io/sync-options: PrunePropagationPolicy=background

However, when PrunePropagationPolicy is set to foreground, the ownership-controlled objects are deleted first, and the owner object is deleted once all dependent objects are deleted. Therefore, if you have a deployment that creates pods and you delete the deployment with a foreground propagation policy, the pods will be deleted first and the deployment will be deleted once all pods are deleted.

With the third setting, orphan, the owner object is deleted but the ownership-controlled objects are left as is. In this example, then, the deployment is deleted but the pods are left running. As you can see, users have extensive flexibility in managing the deletion of resources during pruning in Argo CD.

Sync Waves

At this point you might wonder how the synchronization process happens. Argo CD uses a mechanism known as "sync waves" that allow you to ensure certain resources are healthy before subsequent resources are synced. By default, all resources are assigned to wave 0. However, you can assign a resource to a specific wave by adding an annotation to the resource in the Git repository. The wave can be any integer, positive or negative. Resources with lower wave numbers are synced before resources with higher wave numbers. Resources with the same wave number are synced in parallel.

To assign a resource to a specific wave, use

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-configmap
  annotations:
    argocd.argoproj.io/sync-wave: "10"

When Argo CD starts a sync, it orders the resources by phase, wave, kind, and name. It applies resources in each wave and repeats this process until all phases and waves are in sync and healthy. The ConfigMap my-configmap is assigned to wave 10, which means it will be synced after resources in waves assigned values less than 10 are synced and become healthy. Also worth noting is the delay between each sync wave to give other controllers a chance to react to the spec change. The delay can be configured with the ARGOCD_SYNC_WAVE_DELAY environment variable.

Sync Phases

A sync operation is executed in a number of steps or phases. These phases allow you to control the order of operations and perform specific tasks at different stages of the sync process. At a high level are three phases: The first, PreSync, occurs before the main synchronization of resources. It's typically used to perform setup tasks that need to happen before the main sync, such as creating necessary namespaces or setting up permissions. Only hooks can be used in this phase.

The second phase, Sync, is the main phase of the sync operation, at which time Argo CD applies the desired state from the Git repository to the Kubernetes cluster. This phase includes creating, updating, or deleting resources as necessary to match the desired state.

The third stage, PostSync, occurs after the main synchronization of resources. It's typically used to perform cleanup or validation tasks that need to happen after the main sync, such as running tests or sending notifications. Like the PreSync phase, only hooks can be used.

You can define hooks for the PreSync and PostSync phases by adding annotations to the resources in your Git repository. To define a PreSync hook, use

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-sync-job
  annotations:
    argocd.argoproj.io/hook: PreSync

The Job pre-sync-job will be run during the PreSync phase of the sync operation. Similarly, you can define a PostSync hook with the

argocd.argoproj.io/hook: PostSync

annotation. As you can see, sync phases provide a powerful way to manage the lifecycle of a sync operation in Argo CD, allowing you to perform specific tasks at different stages of the process.