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

     1  # Diff Strategies
     2  
     3  Argo CD calculates the diff between the desired state and the live
     4  state in order to define if an Application is out-of-sync. This same
     5  logic is also used in Argo CD UI to display the differences between
     6  live and desired states for all resources belonging to an application.
     7  
     8  Argo CD currently has 3 different strategies to calculate diffs:
     9  
    10  - **Legacy**: This is the main diff strategy used by default. It
    11    applies a 3-way diff based on live state, desired state and
    12    last-applied-configuration (annotation).
    13  - **Structured-Merge Diff**: Strategy automatically applied when
    14    enabling Server-Side Apply sync option. 
    15  - **Server-Side Diff**: New strategy that invokes a Server-Side Apply
    16    in dryrun mode in order to generate the predicted live state.
    17  
    18  ## Structured-Merge Diff
    19  
    20  !!! warning "Feature Discontinued"
    21      After different issues were identified by the community, this strategy is being discontinued in favour of Server-Side Diff.
    22  
    23  This diff strategy is automatically used when Server-Side Apply
    24  sync option is enabled. It uses the [structured-merge-diff][2] library
    25  used by Kubernetes to calculate diffs based on fields ownership. There
    26  are some challenges using this strategy to calculate diffs for CRDs
    27  that define default values.
    28  
    29  ## Server-Side Diff
    30  *Current Status: Stable (Since v3.1.0)*
    31  
    32  This diff strategy will execute a Server-Side Apply in dryrun mode for
    33  each resource of the application. The response of this operation is then
    34  compared with the live state in order to provide the diff results. The
    35  diff results are cached and new Server-Side Apply requests to Kube API
    36  are only triggered when:
    37  
    38  - An Application refresh or hard-refresh is requested.
    39  - There is a new revision in the repo which the Argo CD Application is
    40    targeting.
    41  - The Argo CD Application spec changed.
    42  - The [Resource Version][3] of the resource itself in live state changed
    43  
    44  One advantage of Server-Side Diff is that Kubernetes Admission
    45  Controllers will participate in the diff calculation. If for example
    46  a validation webhook identifies a resource to be invalid, that will be
    47  informed to Argo CD during the diff stage rather than during the sync 
    48  stage.
    49  
    50  Note that Server-Side Diff will not be performed during the creation of new resources.
    51  This is to save an additional call to KubeAPI and provide a much lighter and faster diff calculation
    52  (Non-Server-Side Apply) when resources don't exist to compare against. During resource creation performing a
    53  Server-Side Diff won't have the benefit of the Kubernetes Admission Controller in the diff stage as validation webhooks 
    54  won't be executed when calculating diffs if the resource is not applied in the cluster yet.
    55  
    56  ### Enabling it
    57  
    58  Server-Side Diff can be enabled at the Argo CD Controller level or per
    59  Application.
    60  
    61  **Enabling Server-Side Diff for all Applications**
    62  
    63  Add the following entry in the argocd-cmd-params-cm configmap:
    64  
    65  ```yaml
    66  apiVersion: v1
    67  kind: ConfigMap
    68  metadata:
    69    name: argocd-cmd-params-cm
    70  data:
    71    controller.diff.server.side: "true"
    72  ...
    73  ```
    74  
    75  Note: It is necessary to restart the `argocd-application-controller`
    76  after applying this configuration.
    77  
    78  **Enabling Server-Side Diff for one application**
    79  
    80  Add the following annotation in the Argo CD Application resource:
    81  
    82  ```yaml
    83  apiVersion: argoproj.io/v1alpha1
    84  kind: Application
    85  metadata:
    86    annotations:
    87      argocd.argoproj.io/compare-options: ServerSideDiff=true
    88  ...
    89  ```
    90  
    91  **Disabling Server-Side Diff for one application**
    92  
    93  If Server-Side Diff is enabled globally in your Argo CD instance, it
    94  is possible to disable it at the application level. In order to do so,
    95  add the following annotation in the Application resource:
    96  
    97  ```yaml
    98  apiVersion: argoproj.io/v1alpha1
    99  kind: Application
   100  metadata:
   101    annotations:
   102      argocd.argoproj.io/compare-options: ServerSideDiff=false
   103  ...
   104  ```
   105  
   106  *Note: Please report any issues that forced you to disable the
   107  Server-Side Diff feature*
   108  
   109  ### Mutation Webhooks
   110  
   111  Server-Side Diff does not include changes made by mutation webhooks by
   112  default. If you want to include mutation webhooks in Argo CD diffs add
   113  the following annotation in the Argo CD Application resource:
   114  
   115  ```yaml
   116  apiVersion: argoproj.io/v1alpha1
   117  kind: Application
   118  metadata:
   119    annotations:
   120      argocd.argoproj.io/compare-options: IncludeMutationWebhook=true
   121  ...
   122  ```
   123  
   124  Note: This annotation is only effective when Server-Side Diff is
   125  enabled. To enable both options for a given application add the
   126  following annotation in the Argo CD Application resource:
   127  
   128  ```yaml
   129  apiVersion: argoproj.io/v1alpha1
   130  kind: Application
   131  metadata:
   132    annotations:
   133      argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
   134  ...
   135  ```
   136  
   137  [1]: https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#beta
   138  [2]: https://github.com/kubernetes-sigs/structured-merge-diff
   139  [3]: https://kubernetes.io/docs/reference/using-api/api-concepts/#resourceversion-in-metadata