mirror of
https://github.com/argoproj/argo-cd
synced 2026-04-21 08:57:17 +00:00
docs: clarify selective sync and ApplyOutOfSyncOnly (#27393)
Signed-off-by: Alexandre Gaudreault <alexandre_gaudreault@intuit.com>
This commit is contained in:
Alexandre Gaudreault
GitHub
parent
4f47dd0afa
commit
4bc5d38634
2 changed files with 46 additions and 50 deletions
|
|
@ -1,15 +1,10 @@
|
|||
# Selective Sync
|
||||
|
||||
A *selective sync* is one where only some resources are sync'd. You can choose which resources from the UI:
|
||||
A _selective sync_ is one where only some resources are sync'd. You can choose which resources from the UI or the CLI:
|
||||
|
||||
|
||||
|
||||
When doing so, bear in mind that:
|
||||
|
||||
* Your sync is not recorded in the history, and so rollback is not possible.
|
||||
* [Hooks](sync-waves.md) are not run.
|
||||
|
||||
## Selective Sync Option
|
||||
|
||||
Turning on selective sync option which will sync only out-of-sync resources.
|
||||
See [sync options](sync-options.md#selective-sync) documentation for more details.
|
||||
- Your sync is **not** recorded in the history, and so rollback is not possible.
|
||||
- [Hooks](sync-waves.md) are **not** run.
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- Prune=false
|
||||
- Prune=false
|
||||
```
|
||||
|
||||
Note that setting a Prune sync option on the resource will always override a
|
||||
|
|
@ -55,14 +55,13 @@ confirmed. The UI will look similar to this, with the "Confirm Pruning" button a
|
|||
|
||||
It is also possible to set this option as a default option on the application level:
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- Prune=confirm
|
||||
- Prune=confirm
|
||||
```
|
||||
|
||||
Note that setting a Prune sync option on the resource will always override a
|
||||
|
|
@ -85,8 +84,7 @@ If you want to exclude a whole class of objects globally, consider setting `reso
|
|||
When syncing a custom resource which is not yet known to the cluster, there are generally two options:
|
||||
|
||||
1. The CRD manifest is part of the same sync. Then Argo CD will automatically skip the dry run, the CRD will be applied and the resource can be created.
|
||||
2. In some cases the CRD is not part of the sync, but it could be created in another way, e.g. by a controller in the cluster. An example is [gatekeeper](https://github.com/open-policy-agent/gatekeeper),
|
||||
which creates CRDs in response to user defined `ConstraintTemplates`. Argo CD cannot find the CRD in the sync and will fail with the error `the server could not find the requested resource`.
|
||||
2. In some cases the CRD is not part of the sync, but it could be created in another way, e.g. by a controller in the cluster. An example is [gatekeeper](https://github.com/open-policy-agent/gatekeeper), which creates CRDs in response to user defined `ConstraintTemplates`. Argo CD cannot find the CRD in the sync and will fail with the error `the server could not find the requested resource`.
|
||||
|
||||
To skip the dry run for missing resource types, use the following annotation:
|
||||
|
||||
|
|
@ -107,7 +105,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- SkipDryRunOnMissingResource=true
|
||||
- SkipDryRunOnMissingResource=true
|
||||
```
|
||||
|
||||
## No Resource Deletion
|
||||
|
|
@ -123,14 +121,13 @@ metadata:
|
|||
|
||||
It is also possible to set this option as a default option on the application level:
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- Delete=false
|
||||
- Delete=false
|
||||
```
|
||||
|
||||
Note that setting a Delete sync option on the resource will always override a
|
||||
|
|
@ -158,21 +155,24 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- Delete=confirm
|
||||
- Delete=confirm
|
||||
```
|
||||
|
||||
Note that setting a Delete sync option on the resource will always override a
|
||||
Delete sync policy defined in the Application.
|
||||
|
||||
## Selective Sync
|
||||
## Apply Resources OutOfSync Only
|
||||
|
||||
Currently, when syncing using auto sync Argo CD applies every object in the application.
|
||||
For applications containing thousands of objects this takes quite a long time and puts undue pressure on the api server.
|
||||
Turning on the selective sync option will sync only out-of-sync resources.
|
||||
The default behavior when syncing your application is to apply every object in the application.
|
||||
For applications containing thousands of objects, this takes quite a long time and puts undue pressure on the Kubernetes API server. It will also significantly increase the size of the `status.operationState.syncResult.resources` field, which may impact the Kubernetes database.
|
||||
|
||||
Turning on the sync option will sync only out-of-sync resources.
|
||||
|
||||
Unlike [Selective Sync](./selective_sync.md), when `ApplyOutOfSyncOnly` is enabled, Sync Hooks will still run and the sync will be recorded in the history.
|
||||
|
||||
You can add this option in the following ways:
|
||||
|
||||
1) Add `ApplyOutOfSyncOnly=true` in manifest
|
||||
1. Add `ApplyOutOfSyncOnly=true` in manifest
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -182,10 +182,10 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- ApplyOutOfSyncOnly=true
|
||||
- ApplyOutOfSyncOnly=true
|
||||
```
|
||||
|
||||
2) Set sync option via argocd cli
|
||||
2. Set sync option via argocd cli
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -205,7 +205,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- PrunePropagationPolicy=foreground
|
||||
- PrunePropagationPolicy=foreground
|
||||
```
|
||||
|
||||
## Prune Last
|
||||
|
|
@ -219,10 +219,11 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- PruneLast=true
|
||||
- PruneLast=true
|
||||
```
|
||||
|
||||
This can also be configured at individual resource level.
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
|
|
@ -236,14 +237,13 @@ By default, Argo CD executes the `kubectl apply` operation to apply the configur
|
|||
`kubectl.kubernetes.io/last-applied-configuration` annotation that is added by `kubectl apply`. In such cases you
|
||||
might use `Replace=true` sync option:
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- Replace=true
|
||||
- Replace=true
|
||||
```
|
||||
|
||||
If the `Replace=true` sync option is set, Argo CD will use `kubectl replace` or `kubectl create` command to apply changes.
|
||||
|
|
@ -253,6 +253,7 @@ If the `Replace=true` sync option is set, Argo CD will use `kubectl replace` or
|
|||
> This sync option has the potential to be destructive and might lead to resources having to be recreated, which could cause an outage for your application.
|
||||
|
||||
This can also be configured at individual resource level.
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
|
|
@ -268,6 +269,7 @@ For certain resources you might want to delete and recreate, e.g. job resources
|
|||
> This sync option has a destructive action, which could cause an outage for your application.
|
||||
|
||||
In such cases you might use `Force=true` sync option in target resources annotation:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
|
|
@ -302,7 +304,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- ServerSideApply=true
|
||||
- ServerSideApply=true
|
||||
```
|
||||
|
||||
To enable ServerSideApply just for an individual resource, the sync-option annotation
|
||||
|
|
@ -323,7 +325,6 @@ metadata:
|
|||
argocd.argoproj.io/sync-options: ServerSideApply=false
|
||||
```
|
||||
|
||||
|
||||
ServerSideApply can also be used to patch existing resources by providing a partial
|
||||
yaml. For example, if there is a requirement to update just the number of replicas
|
||||
in a given Deployment, the following yaml can be provided to Argo CD:
|
||||
|
|
@ -338,7 +339,7 @@ spec:
|
|||
```
|
||||
|
||||
Note that by the Deployment schema specification, this isn't a valid manifest. In this
|
||||
case an additional sync option *must* be provided to skip schema validation. The example
|
||||
case an additional sync option _must_ be provided to skip schema validation. The example
|
||||
below shows how to configure the application to enable the two necessary sync options:
|
||||
|
||||
```yaml
|
||||
|
|
@ -347,8 +348,8 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- ServerSideApply=true
|
||||
- Validate=false
|
||||
- ServerSideApply=true
|
||||
- Validate=false
|
||||
```
|
||||
|
||||
In this case, Argo CD will use the `kubectl apply --server-side --force-conflicts --validate=false` command
|
||||
|
|
@ -368,7 +369,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- ClientSideApplyMigration=false
|
||||
- ClientSideApplyMigration=false
|
||||
```
|
||||
|
||||
You can specify a custom field manager for the client-side apply migration using an annotation:
|
||||
|
|
@ -378,7 +379,7 @@ apiVersion: argoproj.io/v1alpha1
|
|||
kind: Application
|
||||
metadata:
|
||||
annotations:
|
||||
argocd.argoproj.io/client-side-apply-migration-manager: "my-custom-manager"
|
||||
argocd.argoproj.io/client-side-apply-migration-manager: 'my-custom-manager'
|
||||
```
|
||||
|
||||
This is useful when you have other operators managing resources that are no longer in use and would like Argo CD to own all the fields for that operator.
|
||||
|
|
@ -386,6 +387,7 @@ This is useful when you have other operators managing resources that are no long
|
|||
### How it works
|
||||
|
||||
When client-side apply migration is enabled:
|
||||
|
||||
1. Argo CD will use the specified field manager (or default if not specified) to perform migration
|
||||
2. During a server-side apply sync operation, it will:
|
||||
- Check if the specified field manager exists in the resource's `managedFields` with `operation: Update` (indicating client-side apply)
|
||||
|
|
@ -405,7 +407,7 @@ kind: Application
|
|||
spec:
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- FailOnSharedResource=true
|
||||
- FailOnSharedResource=true
|
||||
```
|
||||
|
||||
## Respect ignore differences configs
|
||||
|
|
@ -416,16 +418,15 @@ This sync option is used to enable Argo CD to consider the configurations made i
|
|||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
spec:
|
||||
|
||||
ignoreDifferences:
|
||||
- group: "apps"
|
||||
kind: "Deployment"
|
||||
jsonPointers:
|
||||
- /spec/replicas
|
||||
- group: 'apps'
|
||||
kind: 'Deployment'
|
||||
jsonPointers:
|
||||
- /spec/replicas
|
||||
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- RespectIgnoreDifferences=true
|
||||
- RespectIgnoreDifferences=true
|
||||
```
|
||||
|
||||
The example above shows how an Argo CD Application can be configured so it will ignore the `spec.replicas` field from the desired state (git) during the sync stage. This is achieved by calculating and pre-patching the desired state before applying it in the cluster. Note that the `RespectIgnoreDifferences` sync option is only effective when the resource is already created in the cluster. If the Application is being created and no live state exists, the desired state is applied as-is.
|
||||
|
|
@ -443,7 +444,7 @@ spec:
|
|||
namespace: some-namespace
|
||||
syncPolicy:
|
||||
syncOptions:
|
||||
- CreateNamespace=true
|
||||
- CreateNamespace=true
|
||||
```
|
||||
|
||||
The example above shows how an Argo CD Application can be configured so it will create the namespace specified in `spec.destination.namespace` if it doesn't exist already. Without this either declared in the Application manifest or passed in the CLI via `--sync-option CreateNamespace=true`, the Application will fail to sync if the namespace doesn't exist.
|
||||
|
|
@ -471,7 +472,7 @@ spec:
|
|||
applies: for
|
||||
annotations: on-the-namespace
|
||||
syncOptions:
|
||||
- CreateNamespace=true
|
||||
- CreateNamespace=true
|
||||
```
|
||||
|
||||
In order for Argo CD to manage the labels and annotations on the namespace, `CreateNamespace=true` needs to be set as a
|
||||
|
|
@ -479,14 +480,14 @@ sync option, otherwise nothing will happen. If the namespace doesn't already exi
|
|||
already have labels and/or annotations set on it, you're good to go.
|
||||
|
||||
The generated namespace is normally not tracked with Argo CD. You can use `managedNamespaceMetadata` to
|
||||
set a tracking annotation on the generated namespace, which sets the namespace to be *owned* by Argo CD.
|
||||
set a tracking annotation on the generated namespace, which sets the namespace to be _owned_ by Argo CD.
|
||||
|
||||
Once a namespace is owned by Argo CD, it will be managed by ArgoCD, including the possibility to delete it, which Argo CD normally does not do:
|
||||
|
||||
```yaml
|
||||
managedNamespaceMetadata:
|
||||
annotations:
|
||||
argocd.argoproj.io/tracking-id: "your-application-name:/Namespace:/your-namespace-name"
|
||||
argocd.argoproj.io/tracking-id: 'your-application-name:/Namespace:/your-namespace-name'
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
|
|
@ -500,7 +501,7 @@ client-side-applied resources with server-side-applies. If you do not upgrade th
|
|||
may remove existing labels/annotations, which may or may not be the desired behavior.
|
||||
|
||||
Another thing to keep mind of is that if you have a k8s manifest for the same namespace in your Argo CD application, that
|
||||
will take precedence and *overwrite whatever values that have been set in `managedNamespaceMetadata`*. In other words, if
|
||||
will take precedence and **overwrite whatever values that have been set in `managedNamespaceMetadata`**. In other words, if
|
||||
you have an application that sets `managedNamespaceMetadata`
|
||||
|
||||
```yaml
|
||||
|
|
@ -530,7 +531,7 @@ metadata:
|
|||
The resulting namespace will have its annotations set to
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
foo: bar
|
||||
something: completely-different
|
||||
annotations:
|
||||
foo: bar
|
||||
something: completely-different
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue