Kustomize: overlays для dev и prod

Одно приложение обычно живёт в нескольких средах. В dev одна реплика, мелкие лимиты и подробные логи. На проде три реплики, нормальные лимиты и боевой образ. Отличий немного, а вот копировать ради них весь набор манифестов - плохая идея: копии со временем разъезжаются, и любая общая правка требует обхода всех папок.

Kustomize раскладывает это на слои. Общая часть лежит в base, отличия каждой среды лежат в своём overlay. Overlay подключает base целиком и докидывает поверх только свои правки.

Термины

Base - папка с kustomization.yaml, которая ни от кого не зависит и применяется сама по себе. Overlay - папка с kustomization.yaml, которая ссылается на base через resources и накладывает правки.

Иерархия не ограничена двумя уровнями: overlay сам может служить base для следующего слоя. Такое встречается, когда над общей базой строят слой продукта, а над ним уже слои конкретных регионов.

Структура

base/
  kustomization.yaml      # resources: deployment.yaml, service.yaml
  deployment.yaml         # web, 1 реплика
  service.yaml
overlays/
  dev/
    kustomization.yaml    # resources: ../../base
  prod/
    kustomization.yaml    # resources: ../../base + патч replicas: 3
    patches/
      replicas.yaml

Правило разделения простое: в base попадает то, что одинаково везде, в overlay - только отличия. Если поле совпадает во всех средах, ему место в base.

Overlay ссылается на base

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: shop-prod
namePrefix: prod-
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: web
    patch: |
      - op: replace
        path: /spec/replicas
        value: 3
images:
  - name: nginx
    newTag: "1.25"

В resources указывается путь к папке base, а не к отдельным файлам. Kustomize сначала соберёт base как самостоятельную группу, потом наложит на результат трансформеры и патчи overlay.

Overlay для dev при этом может остаться почти пустым:

# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: shop-dev
namePrefix: dev-
resources:
  - ../../base

Отличий нет - значит и правок нет. Это нормальное состояние, а не признак незаконченной работы.

Применение слоя

kubectl apply -k overlays/prod

Уедет версия с тремя репликами, префиксом prod- и тегом 1.25. Для dev команда та же, только путь другой, и в кластере окажется одна реплика с дефолтным образом из base.

Перед применением полезно сравнить, чем среды отличаются на самом деле:

diff <(kubectl kustomize overlays/dev) <(kubectl kustomize overlays/prod)

Такой diff отвечает на вопрос «что у нас на проде не как в dev» надёжнее, чем чтение конфигурации глазами.

Components

Когда правка нужна не одной среде, а произвольному набору сред, её выносят в component. Это папка с kind: Component вместо kind: Kustomization, которую overlay подключает блоком components:. Типичный пример - включение метрик или отладочного sidecar сразу в нескольких overlay без дублирования патча.

Что обычно ломается

Пути в resources относительны файлу kustomization.yaml, а не текущему каталогу. Из overlays/prod/ до base ведёт ../../base.

Kustomize запрещает подтягивать отдельные файлы, лежащие выше корня сборки. Ссылка на папку с собственным kustomization.yaml работает всегда, а вот resources: ../../common/deployment.yaml упрётся в защиту и выдаст ошибку про файл вне текущего каталога. Решение - сделать из этой папки полноценный base.

kubectl apply -k не удаляет объекты, исчезнувшие из overlay. Ресурс, убранный из конфигурации, остаётся в кластере, пока его не удалят руками или через prune. Из-за этого в GitOps-инструментах у Kustomize обычно включают отдельный механизм сборки мусора.

Разрастание overlay - признак того, что разделение выбрано неудачно. Если в overlay уже пять патчей и половина полей base переопределена, стоит вынести общую часть обратно в base или разбить приложение на два.

Домашка

Теорию закрепляет задание на своём кластере: 1 шаг с проверкой. Кластер поднимается по треку Kubernetes локально, задания лежат в репозитории k8s-practice.

./run.sh start k8s-kustomize-overlays     # развернуть стартовое состояние
./run.sh verify k8s-kustomize-overlays    # проверить текущий шаг

Коротко

• Base самодостаточен и применяется сам по себе; overlay подключает base через resources и правит только отличия.
• Путь в resources указывает на папку с kustomization.yaml, а не на отдельный файл.
• Пути считаются относительно kustomization.yaml, из overlays/prod/ до base это ../../base.
• kubectl apply -k overlays/<env> применяет нужный слой; diff двух рендеров показывает реальные отличия сред.
• Правку, общую для нескольких overlay, выносят в component.