Kustomize commonAnnotations
commonAnnotations adds a fixed set of annotations to every resource the build produces.
Annotations carry non-identifying metadata: a build number, a commit SHA, an ownership tag. commonAnnotations stamps them across an overlay in one place.
What it does
commonAnnotations adds the given key/value pairs to metadata.annotations on every resource and into pod template annotations. Unlike labels, annotations are not used for selection, so there is no selector-immutability concern. Existing annotation keys with the same name are overwritten.
Common usage
commonAnnotations:
app.kubernetes.io/managed-by: kustomize
example.com/git-sha: "abc1234"
example.com/build: "ci-2026-06-30"Behavior
| Aspect | Effect |
|---|---|
| metadata.annotations | Pairs added to every resource |
| pod template annotations | Propagated into spec.template |
| existing same-key annotation | Overwritten by the common value |
| selectors | Not affected (annotations are not selectors) |
In CI
Inject the commit SHA via kustomize edit set annotation or by templating the value before build, so each deploy is traceable to a commit. Annotation values must be strings, so quote numeric-looking values like a build number to avoid YAML parsing them as integers.
Common errors in CI
"cannot unmarshal number into Go value of type string" means an unquoted numeric annotation value; wrap it in quotes. "metadata.annotations: Too long: must have at most 262144 bytes" means the total annotation size exceeds the limit, often from accidentally stuffing a whole file into a value. Overwritten annotations are silent, so do not rely on commonAnnotations to preserve a pre-existing value.