Documentation is unclear about `forceCommonAnnotations` and `forceCommonLabels`

[profiprog]

Summary

In the documentation about Kustomize I found the declarative options forceCommonAnnotations and forceCommonLabels.

It says that:

• forceCommonLabels is a boolean value which defines if it's allowed to override existing labels
• forceCommonAnnotations is a boolean value which defines if it's allowed to override existing annotations

However, this suggests that existing annotations or labels on individual resources will be preserved if these options are not set to true.
But Kustomize itself does not have such behavior — it always replaces existing annotations with commonAnnotations for matching keys.

I initially thought these options meant that commonAnnotations defined in kustomization.yaml would be overridden by the commonAnnotations from the ArgoCD Application when forceCommonAnnotations: true is set.
That part is correct — but it also implies that if forceCommonAnnotations remains false, the override simply won’t happen.
This is not true, because leaving it false actually causes an error like:

Failed to load target state: failed to generate manifest for source 1 of 1: rpc error: code = Unknown desc = /custom-tools/kustomize_v5.7.1/kustomize edit add annotation argocd.argoproj.io/sync-options:Delete=false, Prune=false failed exit status 1: Error: annotation argocd.argoproj.io/sync-options already in kustomization file. Use --force to override. Usage: kustomize edit add annotation [flags] Examples: add annotation {annotationKey1:annotationValue1} {annotationKey2:annotationValue2} Flags: -f, --force overwrite commonAnnotation if it already exists -h, --help help for annotation Global Flags: --stack-trace print a stack-trace on error

So, setting forceCommonAnnotations: true or forceCommonLabels: true simply causes Argo CD to add the --force flag to the command:

kustomize edit add [annotation|label] ${key}:${value}

Motivation

This proposal clarifies the actual behavior to prevent users from misunderstanding these options as affecting resource-level overrides or merge logic in Kustomize.

Proposal

• forceCommonLabels (bool, default false) if true, Argo CD passes --force to kustomize edit add label, allowing existing commonLabels entries to be replaced. If false, Argo CD will fail if the label key already exists

• forceCommonAnnotations (boolean, default false) if true, Argo CD passes --force to kustomize edit add annotation, allowing existing commonAnnotations entries to be replaced. If false, Argo CD will fail if the annotation key already exists