Overlay Kustomize для окружения prod должен увеличить количество реплик Deployment и добавить один дополнительный label на все ресурсы, но после kustomize build overlays/prod в итоговом манифесте реплики не изменились, хотя label появился. В чём разница между strategic merge patch и JSON6902 patch в Kustomize, и как диагностировать, почему конкретный патч не применился так, как ожидалось?

Короткий ответ

Strategic merge patch (patches с фрагментом YAML того же вида, что целевой ресурс) объединяется с базовым манифестом по известным Kubernetes-правилам слияния полей, и если в патче допущена ошибка — неверный kind/name/apiVersion для таргетинга ресурса, или патч описан как часть списка без совпадающего селектора, — Kustomize может просто не найти, к какому ресурсу применить патч, и тихо его пропустить; JSON6902 patch (patches с target + списком операций op/path/value) применяется по точному JSON-пути, и ошибка в path (например, неверный индекс массива контейнеров) приведёт либо к явной ошибке, либо к применению не туда, куда ожидалось — для диагностики нужно запускать kustomize build локально и явно сверять итоговый YAML, а не полагаться только на применение в кластер.

Как это работает подробнее

strategic merge patch требует, чтобы верхнеуровневые поля-идентификаторы (apiVersion, kind, metadata.name) в файле патча точно совпадали с таргетируемым ресурсом — Kustomize ищет ресурс по этим полям и сливает оставшиеся поля по map-подобным правилам Kubernetes (например, список контейнеров сливается по имени name, а не по индексу); JSON6902 patch, напротив, адресует изменения по target (group/version/kind/name) и точным JSON path, что мощнее для точечных изменений (например, поменять один элемент массива по индексу), но более хрупко при изменении структуры базового манифеста.

Пример кода

example.txtКопировать

# overlays/prod/kustomization.yaml
resources:
  - ../../base
patches:
  - path: patch-replicas.yaml
    target:
      kind: Deployment
      name: web
commonLabels:
  tier: prod
# overlays/prod/patch-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5
$ kustomize build overlays/prod | grep -A1 "replicas:"
  replicas: 5

Что использовать на практике

• Практика. для надёжной диагностики стоит всегда прогонять kustomize build overlays/prod > /tmp/out.yaml локально перед kubectl apply, и явно сверять нужные поля (grep -A3 replicas), а не доверять интуиции о том, что патч точно применился; при частых сложных патчах полезно разбивать overlay на несколько явных файлов (patch-replicas.yaml, patch-labels.yaml) с понятными именами, чтобы проще находить, какой конкретно патч за что отвечает.

Подводные камни

• Ошибка. частая ошибка — указать в strategic merge patch неверный metadata.name, отличающийся от реального имени Deployment в base (например, из-за добавленного Kustomize namePrefix), из-за чего патч не находит цель и молча не применяется; другая ошибка — смешивать strategic merge и JSON6902 патчи на один и тот же ресурс в одном overlay без понимания порядка их применения, что приводит к неожиданному финальному результату.