Confusion around add operations on non-existent fields

[lanmarti]

I don't understand the difference between two jsonPatch add operations.

Given a simple deployment deploy.yaml without any annotations defined:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    a-label: foo
  name: my-deployment
spec:
  selector:
    matchLabels:
      a-label: foo
  template:
    metadata:
      labels:
        a-label: foo
    spec: {} # not relevant

First scenario: adding an annotation to the metadata of the deployment, the deployment has no other annotations defined.
kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deploy.yaml

patches:
- target:
    kind: Deployment
    name: my-deployment
  patch: |-
    - op: add
      path: "/metadata/annotations/my-annotation"
      value: bar

Works as expected

Second scenario: adding an annotation to the pod template of the deployment, the pod template has no other annotations defined.
Incorrect patch:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deploy.yaml

patches:
- target:
    kind: Deployment
    name: my-deployment
  patch: |-
    - op: add
      path: "/spec/template/metadata/annotations/my-annotation"
      value: bar

Applying fails with error: Error: add operation does not apply: doc is missing path: "/spec/template/metadata/annotations/my-annotation": missing value

Correct patch:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deploy.yaml

patches:
- target:
    kind: Deployment
    name: my-deployment
  patch: |-
    - op: add
      path: "/spec/template/metadata/annotations"
      value: {}
    - op: add
      path: "/spec/template/metadata/annotations/my-annotation"
      value: bar

In the second scenario, I need to add an empty annotations map before I can add the annotation itself. Why does that need to happen for annotations in the pod template, but not for annotations of the deployment itself?

Tested using kustomize v4.5.7

[JordanP]

Maybe a strategic merge patch could help you here.