github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/applicationset/Progressive-Syncs.md (about)

     1  # Progressive Syncs
     2  
     3  !!! warning "Alpha Feature (Since v2.6.0)"
     4      This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) 
     5      feature that allows you to control the order in which the ApplicationSet controller will create or update the Applications 
     6      owned by an ApplicationSet resource. It may be removed in future releases or modified in backwards-incompatible ways.
     7  
     8  ## Use Cases
     9  The Progressive Syncs feature set is intended to be light and flexible. The feature only interacts with the health of managed Applications. It is not intended to support direct integrations with other Rollout controllers (such as the native ReplicaSet controller or Argo Rollouts).
    10  
    11  * Progressive Syncs watch for the managed Application resources to become "Healthy" before proceeding to the next stage.
    12  * Deployments, DaemonSets, StatefulSets, and [Argo Rollouts](https://argoproj.github.io/argo-rollouts/) are all supported, because the Application enters a "Progressing" state while pods are being rolled out. In fact, any resource with a health check that can report a "Progressing" status is supported.
    13  * [Argo CD Resource Hooks](../../user-guide/resource_hooks.md) are supported. We recommend this approach for users that need advanced functionality when an Argo Rollout cannot be used, such as smoke testing after a DaemonSet change.
    14  
    15  ## Enabling Progressive Syncs
    16  As an experimental feature, progressive syncs must be explicitly enabled, in one of these ways.
    17  
    18  1. Pass `--enable-progressive-syncs` to the ApplicationSet controller args.
    19  1. Set `ARGOCD_APPLICATIONSET_CONTROLLER_ENABLE_PROGRESSIVE_SYNCS=true` in the ApplicationSet controller environment variables.
    20  1. Set `applicationsetcontroller.enable.progressive.syncs: true` in the Argo CD `argocd-cmd-params-cm` ConfigMap.
    21  
    22  ## Strategies
    23  
    24  ApplicationSet strategies control both how applications are created (or updated) and deleted. These operations are configured using two separate fields:
    25  
    26  * **Creation Strategy** (`type` field): Controls application creation and updates
    27  * **Deletion Strategy** (`deletionOrder` field): Controls application deletion order
    28  
    29  ### Creation Strategies
    30  
    31  The `type` field controls how applications are created and updated. Available values:
    32  
    33  * **AllAtOnce** (default)
    34  * **RollingSync**
    35  
    36  #### AllAtOnce
    37  This default Application update behavior is unchanged from the original ApplicationSet implementation.
    38  
    39  All Applications managed by the ApplicationSet resource are updated simultaneously when the ApplicationSet is updated.
    40  
    41  ```yaml
    42  spec:
    43    strategy:
    44      type: AllAtOnce  # explicit, but this is the default
    45  ```
    46  
    47  #### RollingSync
    48  This update strategy allows you to group Applications by labels present on the generated Application resources.
    49  When the ApplicationSet changes, the changes will be applied to each group of Application resources sequentially.
    50  
    51  * Application groups are selected using their labels and `matchExpressions`.
    52  * All `matchExpressions` must be true for an Application to be selected (multiple expressions match with AND behavior).
    53  * The `In` and `NotIn` operators must match at least one value to be considered true (OR behavior).
    54  * The `NotIn` operator has priority in the event that both a `NotIn` and `In` operator produce a match.
    55  * All Applications in each group must become Healthy before the ApplicationSet controller will proceed to update the next group of Applications.
    56  * The number of simultaneous Application updates in a group will not exceed its `maxUpdate` parameter (default is 100%, unbounded).
    57  * RollingSync will capture external changes outside the ApplicationSet resource, since it relies on watching the OutOfSync status of the managed Applications.
    58  * RollingSync will force all generated Applications to have autosync disabled. Warnings are printed in the applicationset-controller logs for any Application specs with an automated syncPolicy enabled.
    59  * Sync operations are triggered the same way as if they were triggered by the UI or CLI (by directly setting the `operation` status field on the Application resource). This means that a RollingSync will respect sync windows just as if a user had clicked the "Sync" button in the Argo UI.
    60  * When a sync is triggered, the sync is performed with the same syncPolicy configured for the Application. For example, this preserves the Application's retry settings.
    61  * If an Application is considered "Pending" for `applicationsetcontroller.default.application.progressing.timeout` seconds, the Application is automatically moved to Healthy status (default 300).
    62  * If an Application is not selected in any step, it will be excluded from the rolling sync and needs to be manually synced through the CLI or UI.
    63  
    64  ```yaml
    65  spec:
    66    strategy:
    67      type: RollingSync
    68      rollingSync:
    69        steps:
    70          - matchExpressions:
    71              - key: envLabel
    72                operator: In
    73                values:
    74                  - env-dev
    75          - matchExpressions:
    76              - key: envLabel
    77                operator: In
    78                values:
    79                  - env-prod
    80            maxUpdate: 10%
    81  ```
    82  
    83  ### Deletion Strategies
    84  
    85  The `deletionOrder` field controls the order in which applications are deleted when they are removed from the ApplicationSet. Available values:
    86  
    87  * **AllAtOnce** (default)
    88  * **Reverse**
    89  
    90  #### AllAtOnce Deletion
    91  This is the default behavior where all applications that need to be deleted are removed simultaneously. This works with both `AllAtOnce` and `RollingSync` creation strategies.
    92  
    93  ```yaml
    94  spec:
    95    strategy:
    96      type: RollingSync  # or AllAtOnce
    97      deletionOrder: AllAtOnce  # explicit, but this is the default
    98  ```
    99  
   100  #### Reverse Deletion
   101  When using `deletionOrder: Reverse` with RollingSync strategy, applications are deleted in reverse order of the steps defined in `rollingSync.steps`. This ensures that applications deployed in later steps are deleted before applications deployed in earlier steps.
   102  This strategy is particularly useful when you need to tear down dependent services in the particular sequence.
   103  
   104  **Requirements for Reverse deletion:**
   105  - Must be used with `type: RollingSync` 
   106  - Requires `rollingSync.steps` to be defined
   107  - Applications are deleted in reverse order of step sequence
   108  
   109  **Important:** The ApplicationSet finalizer is not removed until all applications are successfully deleted. This ensures proper cleanup and prevents the ApplicationSet from being removed before its managed applications.
   110  
   111  ```yaml
   112  spec:
   113    strategy:
   114      type: RollingSync
   115      deletionOrder: Reverse
   116      rollingSync:
   117        steps:
   118          - matchExpressions:
   119              - key: envLabel
   120                operator: In
   121                values:
   122                  - env-dev        # Step 1: Created first, deleted last
   123          - matchExpressions:
   124              - key: envLabel  
   125                operator: In
   126                values:
   127                  - env-prod       # Step 2: Created second, deleted first
   128  ```
   129  
   130  In this example, when applications are deleted:
   131  1. `env-prod` applications (Step 2) are deleted first
   132  2. `env-dev` applications (Step 1) are deleted second
   133  
   134  This deletion order is useful for scenarios where you need to tear down dependent services in the correct sequence, such as deleting frontend services before backend dependencies.
   135  
   136  #### Example
   137  The following example illustrates how to stage a progressive sync over Applications with explicitly configured environment labels.
   138  
   139  Once a change is pushed, the following will happen in order.
   140  
   141  * All `env-dev` Applications will be updated simultaneously.
   142  * The rollout will wait for all `env-qa` Applications to be manually synced via the `argocd` CLI or by clicking the Sync button in the UI.
   143  * 10% of all `env-prod` Applications will be updated at a time until all `env-prod` Applications have been updated.
   144  
   145  ```yaml
   146  apiVersion: argoproj.io/v1alpha1
   147  kind: ApplicationSet
   148  metadata:
   149    name: guestbook
   150  spec:
   151    generators:
   152    - list:
   153        elements:
   154        - cluster: engineering-dev
   155          url: https://1.2.3.4
   156          env: env-dev
   157        - cluster: engineering-qa
   158          url: https://2.4.6.8
   159          env: env-qa
   160        - cluster: engineering-prod
   161          url: https://9.8.7.6/
   162          env: env-prod
   163    strategy:
   164      type: RollingSync
   165      deletionOrder: Reverse  # Applications will be deleted in reverse order of steps
   166      rollingSync:
   167        steps:
   168          - matchExpressions:
   169              - key: envLabel
   170                operator: In
   171                values:
   172                  - env-dev
   173            #maxUpdate: 100%  # if undefined, all applications matched are updated together (default is 100%)
   174          - matchExpressions:
   175              - key: envLabel
   176                operator: In
   177                values:
   178                  - env-qa
   179            maxUpdate: 0      # if 0, no matched applications will be updated
   180          - matchExpressions:
   181              - key: envLabel
   182                operator: In
   183                values:
   184                  - env-prod
   185            maxUpdate: 10%    # maxUpdate supports both integer and percentage string values (rounds down, but floored at 1 Application for >0%)
   186    goTemplate: true
   187    goTemplateOptions: ["missingkey=error"]
   188    template:
   189      metadata:
   190        name: '{{.cluster}}-guestbook'
   191        labels:
   192          envLabel: '{{.env}}'
   193      spec:
   194        project: my-project
   195        source:
   196          repoURL: https://github.com/infra-team/cluster-deployments.git
   197          targetRevision: HEAD
   198          path: guestbook/{{.cluster}}
   199        destination:
   200          server: '{{.url}}'
   201          namespace: guestbook
   202  ```