marcel/argo-cd
1
0
Fork 0
mirror of https://github.com/argoproj/argo-cd.git synced 2026-02-20 01:28:45 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: set default tracking to annotation (#22289)

Browse Source 
Signed-off-by: Yuan Tang <terrytangyuan@gmail.com>
Signed-off-by: Michael Crenshaw <350466+crenshaw-dev@users.noreply.github.com>
Co-authored-by: Yuan Tang <terrytangyuan@gmail.com>
This commit is contained in:
Michael Crenshaw
2025-03-13 17:40:51 -04:00
committed by GitHub
parent 910b9518e4
commit aeb0002877
7 changed files with 104 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/operator-manual/argocd-cm.yaml
View File

@@ -280,9 +280,9 @@ data:
# You can change the resource tracking method Argo CD uses by changing the
# setting application.resourceTrackingMethod to the desired method.
# The following methods are available:
# - label : Uses the application.instanceLabelKey label for tracking
# - annotation : Uses an annotation with additional metadata for tracking instead of the label
# - annotation+label : Also uses an annotation for tracking, but additionally labels the resource with the application name
# - label : Uses the application.instanceLabelKey label for tracking
application.resourceTrackingMethod: annotation
# Optional installation id. Allows to have multiple installations of Argo CD in the same cluster.

52
docs/operator-manual/upgrading/2.14-3.0.md
View File

@@ -228,6 +228,58 @@ Explanation:
- In Helm 3.17.1, this behavior changed and `null` object in `values.yaml` still results in this warning upon performing `helm template`, but the resulting K8s object will be overridden with the invalid `null` value.
- To resolve the issue, identify `values.yaml` with `null` object values, and remove those `null` values.
### Use Annotation-Based Tracking by Default
The default behavior for [tracking resources](../../user-guide/resource_tracking.md) has changed to use annotation-based
tracking instead of label-based tracking. Annotation-based tracking is more reliable and less prone to errors caused by
external code copying tracking labels from one resource to another.
#### Detection
To detect if you are impacted, check the `argocd-cm` ConfigMap for the `application.resourceTrackingMethod` field. If it
unset or is set to `label`, you are using label-based tracking. If it is set to `annotation`, you are already using
annotation-based tracking and are not impacted by this change.
```sh
kubectl get cm argocd-cm -n argocd -o jsonpath='{.data.application\.resourceTrackingMethod}'
```
#### Remediation
For most users, it is safe to upgrade to Argo CD 3.0 and use annotation-based tracking. Labels will be replaced with
annotations on the next sync. Applications will not be marked as out-of-sync if the labels are not present on the
resources.
!!! warning "Potential for orphaned resources"
There is a known edge case when switching from label-based tracking to annotation-based tracking that may cause
resources to be orphaned. If the first sync operation after switching to annotation-based tracking includes a
resource being deleted, Argo CD will fail to recognize that the resource is managed by the Application and will not
delete it. To avoid this edge case, it is recommended to perform a sync operation on your Applications, even if
they are not out of sync, so that orphan resource detection will work as expected on the next sync.
Some users rely on label-based tracking to track resources that are not managed by Argo CD. They may set annotations
to have Argo CD ignore the resource as extraneous or to disable pruning. If you are using label-based tracking to track
resources that are not managed by Argo CD, you will need to construct tracking annotations instead of tracking labels
and apply them to the relevant resources. The format of the tracking annotation is:
```yaml
argocd.argoproj.io/tracking-id: <app name>:<resource group>/<resource kind>:<resource namespace>/<resource name>
```
For cluster-scoped resources, the namespace is set to the value in the Application's `spec.destination.namespace` field.
!!! warning
Manually constructing and applying tracking labels and annotations is not an officially-supported feature, and Argo
CD's behavior may change in the future. It is recommended to manage resources with Argo CD via GitOps.
#### Opting Out
If you are not ready to use annotation-based tracking, you can opt out of this change by setting the
`application.resourceTrackingMethod` field in the `argocd-cm` ConfigMap to `label`. There are no current plans to remove
label-based tracking.
## Other changes
### Using `cluster.inClusterEnabled: "false"`

82
docs/user-guide/resource_tracking.md
View File

@@ -1,8 +1,46 @@
# Resource Tracking
## Tracking Kubernetes resources by annotation
Argo CD can be instructed to use the following methods for tracking:
1. `annotation` (default) - Argo CD uses the `argocd.argoproj.io/tracking-id` annotation to track application resources. Use this when you don't need to maintain both the label and the annotation.
1. `annotation+label` - Argo CD uses the `app.kubernetes.io/instance` label but only for informational purposes. The label is not used for tracking purposes, and the value is still truncated if longer than 63 characters. The annotation `argocd.argoproj.io/tracking-id` is used instead to track application resources. Use this for resources that you manage with Argo CD, but still need compatibility with other tools that require the instance label.
1. `label` - Argo CD uses the `app.kubernetes.io/instance` label
Here is an example of using the annotation method for tracking resources:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
namespace: default
annotations:
argocd.argoproj.io/tracking-id: my-app:apps/Deployment:default/my-deployment
```
The advantages of using the tracking id annotation is that there are no clashes any
more with other Kubernetes tools and Argo CD is never confused about the owner of a resource. The `annotation+label` can also be used if you want other tools to understand resources managed by Argo CD.
### Installation ID
If you are managing one cluster using multiple Argo CD instances, you will need to set `installationID` in the Argo CD ConfigMap. This will prevent conflicts between
the different Argo CD instances:
* Each managed resource will have the annotation `argocd.argoproj.io/installation-id: <installation-id>`
* It is possible to have applications with the same name in Argo CD instances without causing conflicts.
### Non self-referencing annotations
When using the tracking method `annotation` or `annotation+label`, Argo CD will consider the resource properties in the annotation (name, namespace, group and kind) to determine whether the resource should be compared against the desired state. If the tracking annotation does not reference the resource it is applied to, the resource will neither affect the application's sync status nor be marked for pruning.
This allows other kubernetes tools (e.g. [HNC](https://github.com/kubernetes-sigs/hierarchical-namespaces)) to copy a resource to a different namespace without impacting the Argo CD application's sync status. Copied resources will be visible on the UI at top level. They will have no sync status and won't impact the application's sync status.
## Tracking Kubernetes resources by label
Argo CD identifies resources it manages by setting the application instance label to the name of the managing Application on all resources that are managed (i.e. reconciled from Git). The default label used is the well-known label `app.kubernetes.io/instance`.
In this mode, Argo CD identifies resources it manages by setting the application instance label to the name of the managing Application on all resources that are managed (i.e. reconciled from Git). The default label used is the well-known label `app.kubernetes.io/instance`.
Example:
@@ -40,44 +78,6 @@ data:
application.instanceLabelKey: argocd.argoproj.io/instance
```
## Additional tracking methods via an annotation
>v2.2
To offer more flexible options for tracking resources and solve some of the issues outlined in the previous section Argo CD can be instructed to use the following methods for tracking:
1. `label` (default) - Argo CD uses the `app.kubernetes.io/instance` label
1. `annotation+label` - Argo CD uses the `app.kubernetes.io/instance` label but only for informational purposes. The label is not used for tracking purposes, and the value is still truncated if longer than 63 characters. The annotation `argocd.argoproj.io/tracking-id` is used instead to track application resources. Use this for resources that you manage with Argo CD, but still need compatibility with other tools that require the instance label.
1. `annotation` - Argo CD uses the `argocd.argoproj.io/tracking-id` annotation to track application resources. Use this when you don't need to maintain both the label and the annotation.
Here is an example of using the annotation method for tracking resources:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
namespace: default
annotations:
argocd.argoproj.io/tracking-id: my-app:apps/Deployment:default/nginx-deployment
```
The advantages of using the tracking id annotation is that there are no clashes any
more with other Kubernetes tools and Argo CD is never confused about the owner of a resource. The `annotation+label` can also be used if you want other tools to understand resources managed by Argo CD.
### Installation ID
If you are managing one cluster using multiple Argo CD instances, you will need to set `installationID` in the Argo CD ConfigMap. This will prevent conflicts between
the different Argo CD instances:
* Each managed resource will have the annotation `argocd.argoproj.io/tracking-id: <installation-id>`
* It is possible to have applications with the same name in Argo CD instances without causing conflicts.
### Non self-referencing annotations
When using the tracking method `annotation` or `annotation+label`, Argo CD will consider the resource properties in the annotation (name, namespace, group and kind) to determine whether the resource should be compared against the desired state. If the tracking annotation does not reference the resource it is applied to, the resource will neither affect the application's sync status nor be marked for pruning.
This allows other kubernetes tools (e.g. [HNC](https://github.com/kubernetes-sigs/hierarchical-namespaces)) to copy a resource to a different namespace without impacting the Argo CD application's sync status. Copied resources will be visible on the UI at top level. They will have no sync status and won't impact the application's sync status.
## Choosing a tracking method
To actually select your preferred tracking method edit the `resourceTrackingMethod` value contained inside the `argocd-cm` configmap.
@@ -93,8 +93,8 @@ metadata:
data:
application.resourceTrackingMethod: annotation
```
Possible values are `label`, `annotation+label` and `annotation` as described in the previous section.
Possible values are `label`, `annotation+label` and `annotation` as described above.
Note that once you change the value you need to sync your applications again (or wait for the sync mechanism to kick-in) in order to apply your changes.
You can revert to a previous choice, by changing again the configmap.
You can revert to a previous choice, by changing the configmap again.

2
test/e2e/app_management_test.go
View File

@@ -1262,6 +1262,7 @@ definitions:
result = {}
result[1] = impactedResource1
obj.metadata.labels = {}
obj.metadata.labels["aKey"] = 'aValue'
impactedResource2 = {}
impactedResource2.operation = "patch"
@@ -2691,6 +2692,7 @@ func TestSwitchTrackingMethod(t *testing.T) {
func TestSwitchTrackingLabel(t *testing.T) {
ctx := Given(t)
require.NoError(t, fixture.SetTrackingMethod(string(argo.TrackingMethodLabel)))
ctx.
Path("deployment").
When().

7
test/e2e/deployment_test.go
View File

@@ -115,10 +115,9 @@ func TestDeploymentWithoutTrackingMode(t *testing.T) {
And(func(_ *Application) {
out, err := RunCli("app", "manifests", ctx.AppName())
require.NoError(t, err)
assert.Contains(t, out, fmt.Sprintf(`labels:
app: nginx
app.kubernetes.io/instance: %s
`, ctx.AppName()))
assert.Contains(t, out, fmt.Sprintf(`annotations:
argocd.argoproj.io/tracking-id: %s:apps/Deployment:%s/nginx-deployment
`, ctx.AppName(), DeploymentNamespace()))
})
}

3
test/e2e/helm_test.go
View File

@@ -544,8 +544,9 @@ func TestHelmRepoDiffLocal(t *testing.T) {
"--key-file", "../fixture/certs/argocd-test-client.key",
"--ca-file", "../fixture/certs/argocd-test-ca.crt",
))
diffOutput := errors.NewHandler(t).FailOnErr(fixture.RunCli("app", "diff", app.Name, "--local", "testdata/helm")).(string)
diffOutput, err := fixture.RunCli("app", "diff", app.Name, "--local", "testdata/helm")
assert.Empty(t, diffOutput)
assert.NoError(t, err)
})
}

14
util/argo/resource_tracking.go
View File

@@ -55,7 +55,7 @@ func NewResourceTracking() ResourceTracking {
func GetTrackingMethod(settingsMgr *settings.SettingsManager) v1alpha1.TrackingMethod {
tm, err := settingsMgr.GetTrackingMethod()
if err != nil || tm == "" {
return TrackingMethodLabel
return TrackingMethodAnnotation
}
return v1alpha1.TrackingMethod(tm)
}
@@ -100,11 +100,7 @@ func (rt *resourceTracking) GetAppName(un *unstructured.Unstructured, key string
case TrackingMethodAnnotation:
return retrieveAppInstanceValue()
default:
label, err := kube.GetAppInstanceLabel(un, key)
if err != nil {
return ""
}
return label
return retrieveAppInstanceValue()
}
}
@@ -185,11 +181,7 @@ func (rt *resourceTracking) SetAppInstance(un *unstructured.Unstructured, key, v
}
return nil
default:
err := kube.SetAppInstanceLabel(un, key, val)
if err != nil {
return fmt.Errorf("failed to set app instance label: %w", err)
}
return nil
return setAppInstanceAnnotation()
}
}