github.com/argoproj/argo-cd/v3@v3.2.1/docs/user-guide/sync-waves.md (about)

     1  # Sync Phases and Waves
     2  
     3  Sync phases and hooks define when resources are applied such as before or after the main sync operation. This makes it possible to define jobs, or any other resource to run or be applied in any specific order.
     4  
     5  Argo CD has the following hook types:
     6  
     7  | Hook | Description |
     8  |------|-------------|
     9  | `PreSync` | Executes prior to the application of the manifests. |
    10  | `Sync`  | Executes after all `PreSync` hooks completed and were successful, at the same time as the application of the manifests. |
    11  | `Skip` | Indicates to Argo CD to skip the application of the manifest. |
    12  | `PostSync` | Executes after all `Sync` hooks completed and were successful, a successful application, and all resources in a `Healthy` state. |
    13  | `SyncFail` | Executes when the sync operation fails. |
    14  | `PostDelete` | Executes after all Application resources are deleted. _Available starting in v2.10._ |
    15  
    16  Adding the argocd.argoproj.io/hook annotation to a resource will assign it to a specific phase. During a Sync operation, Argo CD will apply the resource during the appropriate phase of the deployment. Hooks can be any type of Kubernetes resource kind, but tend to be Pod, Job or Argo Workflows. Multiple hooks can be specified as a comma separated list.
    17  
    18  ## How phases work?
    19  
    20  Argo CD will respect resources assigned to different phases, during a sync operation Argo CD will do the following.
    21  
    22  Apply all the resources marked as PreSync hooks. If any of them fails the whole sync process will stop and will be marked as failed
    23  Apply all the resources marked as Sync hooks. If any of them fails the whole sync process will be marked as failed. Hooks marked with SyncFail will also run
    24  Apply all the resources marked as PostSync hooks. If any of them fails the whole sync process will be marked as failed.
    25  Hooks marked with Skip will not be applied.
    26  
    27  Here is a graphical overview of the sync process:
    28  
    29  ![phases](how_phases_work.png)
    30  
    31  You can use this simple lifecycle method in various scenarios. For example you can run an essential check as a PreSync hook. If it fails then the whole sync operation will stop preventing the deployment from taking place. In a similar manner you can run smoke tests as PostSync hooks. If they succeed you know that your application has passed the validation. If they fail then the whole deployment will be marked as failed and Argo CD can then notify you in order to take further actions.
    32  
    33  Hooks at the SyncFail phase can be used for cleanup actions and other housekeeping tasks. Note that if they themselves fail, Argo CD will not do anything special (other than marking the whole operation as failed).
    34  
    35  Note that hooks do not run during a selective sync operation.
    36  
    37  ## Hook lifecycle and cleanup
    38  
    39  Argo CD offers several methods to clean up hooks and decide how much history will be kept for previous runs.
    40  In the most basic case you can use the argocd.argoproj.io/hook-delete-policy to decide when a hook will be deleted.
    41  This can take the following values:
    42  
    43  | Policy | Description |
    44  |--------|-------------|
    45  | `HookSucceeded` | The hook resource is deleted after the hook succeeded (e.g. Job/Workflow completed successfully). |
    46  | `HookFailed` | The hook resource is deleted after the hook failed. |
    47  | `BeforeHookCreation` | Any existing hook resource is deleted before the new one is created (since v1.3). It is meant to be used with `/metadata/name`. |
    48  
    49  
    50  ## How sync waves work?
    51  
    52  Argo CD also offers an alternative method of changing the sync order of resources. These are sync waves. They are defined by the argocd.argoproj.io/sync-wave annotation. The value is an integer that defines the ordering (ArgoCD will start deploying from the lowest number and finish with the highest number).
    53  
    54  Hooks and resources are assigned to wave 0 by default. The wave can be negative, so you can create a wave that runs before all other resources.
    55  
    56  When a sync operation takes place, Argo CD will:
    57  Order all resources according to their wave (lowest to highest)
    58  Apply the resources according to the resulting sequence
    59  
    60  There is currently a delay between each sync wave in order to give other controllers a chance to react to the spec change that was just applied. This also prevents Argo CD from assessing resource health too quickly (against the stale object), causing hooks to fire prematurely. The current delay between each sync wave is 2 seconds and can be configured via the environment variable ARGOCD_SYNC_WAVE_DELAY.
    61  
    62  ## Combining Sync waves and hooks
    63  
    64  While you can use sync waves on their own, for maximum flexibility you can combine them with hooks. This way you can use sync phases for coarse grained ordering and sync waves for defining the exact order of a resource within an individual phase.
    65  
    66  ![waves](how_waves_work.png)
    67  
    68  When Argo CD starts a sync, it orders the resources in the following precedence:
    69  
    70  The phase
    71  The wave they are in (lower values first)
    72  By kind (e.g. namespaces first and then other Kubernetes resources, followed by custom resources)
    73  By name
    74  
    75  Once the order is defined:
    76  
    77  First Argo CD determines the number of the first wave to apply. This is the first number where any resource is out-of-sync or unhealthy.
    78  It applies resources in that wave.
    79  It repeats this process until all phases and waves are in-sync and healthy.
    80  
    81  Because an application can have resources that are unhealthy in the first wave, it may be that the app can never get to healthy.
    82  
    83  ## How Do I Configure Phases?
    84  
    85  Pre-sync and post-sync can only contain hooks. Apply the hook annotation:
    86  
    87  ```yaml
    88  metadata:
    89    annotations:
    90      argocd.argoproj.io/hook: PreSync
    91  ```
    92  
    93  [Read more about hooks](resource_hooks.md).
    94  
    95  ## How Do I Configure Waves?
    96  
    97  Specify the wave using the following annotation:
    98  
    99  ```yaml
   100  metadata:
   101    annotations:
   102      argocd.argoproj.io/sync-wave: "5"
   103  ```
   104  
   105  Hooks and resources are assigned to wave zero by default. The wave can be negative, so you can create a wave that runs before all other resources.
   106  
   107  ## Examples
   108  
   109  ### Send message to Slack when sync completes
   110  
   111  The following example uses the Slack API to send a a Slack message when sync completes:
   112  
   113  ```yaml
   114  apiVersion: batch/v1
   115  kind: Job
   116  metadata:
   117    generateName: app-slack-notification-
   118    annotations:
   119      argocd.argoproj.io/hook: PostSync
   120      argocd.argoproj.io/hook-delete-policy: HookSucceeded
   121  spec:
   122    template:
   123      spec:
   124        containers:
   125          - name: slack-notification
   126            image: curlimages/curl
   127            command:
   128              - curl
   129              - '-X'
   130              - POST
   131              - '--data-urlencode'
   132              - >-
   133                payload={"channel": "#somechannel", "username": "hello", "text":
   134                "App Sync succeeded", "icon_emoji": ":ghost:"}
   135              - 'https://hooks.slack.com/services/...'
   136        restartPolicy: Never
   137    backoffLimit: 2
   138  ```
   139  
   140  The following example runs a db migration command before the main sync operation (also in wave -1):
   141  ```yaml
   142  apiVersion: batch/v1
   143  kind: Job
   144  metadata:
   145    name: db-migrate
   146    annotations:
   147      argocd.argoproj.io/hook: PreSync
   148      argocd.argoproj.io/hook-delete-policy: HookSucceeded
   149      argocd.argoproj.io/sync-wave: '-1'
   150  spec:
   151    ttlSecondsAfterFinished: 360
   152    template:
   153      spec:
   154        containers:
   155          - name: postgresql-client
   156            image: 'my-postgres-data:11.5'
   157            imagePullPolicy: Always
   158            env:
   159              - name: PGPASSWORD
   160                value: admin
   161              - name: POSTGRES_HOST
   162                value: my_postgresql_db
   163            command:
   164              - psql
   165              - '-h=my_postgresql_db'
   166              - '-U postgres'
   167              - '-f preload.sql'
   168        restartPolicy: Never
   169    backoffLimit: 1
   170  ```
   171  
   172  ### Work around ArgoCD sync failure
   173  
   174  Upgrading ingress-nginx controller (managed by helm) with ArgoCD 2.x sometimes fails to work resulting in:
   175  
   176  .|.
   177  -|-
   178  OPERATION|Sync
   179  PHASE|Running
   180  MESSAGE|waiting for completion of hook batch/Job/ingress-nginx-admission-create
   181  
   182  .|.
   183  -|-
   184  KIND     |batch/v1/Job
   185  NAMESPACE|ingress-nginx
   186  NAME     |ingress-nginx-admission-create
   187  STATUS   |Running
   188  HOOK     |PreSync
   189  MESSAGE  |Pending deletion
   190  
   191  To work around this, a helm user can add:
   192  
   193  ```yaml
   194  ingress-nginx:
   195    controller:
   196      admissionWebhooks:
   197        annotations:
   198          argocd.argoproj.io/hook: Skip
   199  ```
   200  
   201  Which results in a successful sync.