Краткое введение в Kustomize

Отislander

Kustomize — это инструмент, позволяющий пользователям «настраивать простые и свободные от шаблонов файлы YAML под различные цели, оставляя оригинальный YAML нетронутым и пригодным для использования» (описание позаимствовано из репозитория kustomize на GitHub).

Kustomize можно запускать как отдельный бинарник или использовать встроенную в kubectl функциональность через флаг -k (доступен начиная с Kubernetes 1.14). Важно отметить: отдельный бинарник, как правило, обновляется быстрее, чем версия, встроенная в kubectl, поэтому в сложных сценариях может потребоваться именно standalone-версия .

В своей простейшей форме Kustomize — это набор ресурсов (YAML-файлов, определяющих объекты Kubernetes: Deployments, Services и т.д.) плюс список инструкций по изменениям, которые необходимо внести в эти ресурсы. Подобно тому, как make использует инструкции из Makefile, а Docker собирает контейнер на основе Dockerfile, Kustomize использует kustomization.yaml для хранения предписаний о том, какие изменения пользователь хочет внести в набор ресурсов .

Базовый пример и его актуализация

Исторический пример из оригинальной статьи выглядел так:

resources:
- deployment.yaml
- service.yaml
namePrefix: dev-
namespace: development
commonLabels:
  environment: development

Важное обновление: поле commonLabels было объявлено устаревшим (deprecated) начиная с версии Kustomize v5.0.0. На смену ему пришло поле labels, которое позволяет более гибко управлять добавлением меток — в частности, не инжектировать их автоматически в селекторы ресурсов . Для автоматической миграции можно выполнить команду kustomize edit fix.

Актуализированный эквивалент приведённого выше примера:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
namePrefix: dev-
namespace: development
labels:
- pairs:
    environment: development
  includeSelectors: true

Обратите внимание на includeSelectors: true: оно воспроизводит поведение старого commonLabels, добавляя метку и в селекторы. Однако следует помнить, что менять селекторы уже применённых в кластере ресурсов (Deployments, Services) не рекомендуется — это может привести к сбоям, поскольку поле spec.selector у Deployment является неизменяемым . Если метка нужна только для идентификации, а не для связывания селекторов, includeSelectors можно опустить (по умолчанию false).

Краткое объяснение актуальных полей:

resources — указывает, какие ресурсы будет обрабатывать Kustomize (файлы deployment.yaml и service.yaml в текущем каталоге или относительные пути к ним).

namePrefix — добавляет префикс (в данном случае dev-) к атрибуту name всех ресурсов. Например, nginx-deployment превратится в dev-nginx-deployment.

namespace — добавляет указанное пространство имён ко всем ресурсам.

labels — добавляет набор меток ко всем ресурсам. В отличие от устаревшего commonLabels, позволяет управлять тем, попадут ли метки в селекторы (includeSelectors) и в шаблоны Pod’ов (includeTemplates) .

Сборка и применение

Если выполнить kustomize build . в директории с kustomization.yaml и необходимыми ресурсами, на выходе получится итоговый YAML с учётом всех трансформаций. Вывод детерминирован: при одинаковых входных данных результат всегда будет одним и тем же, поэтому сохранять его в файл необязательно — можно сразу передать в kubectl:

kustomize build . | kubectl apply -f -

Или, используя встроенную в kubectl функциональность (начиная с Kubernetes 1.14):

kubectl apply -k .

Флаг -k фактически заменяет собой kustomize build | kubectl apply -f -, что делает его удобным для повседневного использования .

Зачем это нужно: проблема форков и overlays

Читатели могут спросить: «Зачем нужны все эти сложности, если можно отредактировать файлы напрямую?» В простом примере действительно можно модифицировать deployment.yaml и service.yaml вручную. Но что, если они являются форком чьего-либо проекта? Прямое редактирование затрудняет (если вообще не делает невозможным) rebase форка при обновлении исходника. Kustomize позволяет централизовать изменения в kustomization.yaml, оставив оригинальные файлы нетронутыми.

Преимущества становятся очевидны в сценариях с базовой конфигурацией и множеством её вариантов — так называемыми overlays. Предположим, есть базовая директория с ресурсами nginx и три окружения: development, staging и production.

Структура каталогов:

- base
  - deployment.yaml
  - service.yaml
  - kustomization.yaml
- overlays
  - dev
    - kustomization.yaml
  - staging
    - kustomization.yaml
  - prod
    - kustomization.yaml

В base/kustomization.yaml просто объявляются ресурсы:

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

В каждом из overlays/{dev,staging,prod}/kustomization.yaml пользователи ссылаются на базовую конфигурацию в поле resources и указывают изменения для конкретного окружения. Например, overlays/dev/kustomization.yaml (актуализированная версия):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
namePrefix: dev-
namespace: development
labels:
- pairs:
    environment: development
  includeSelectors: true

А overlays/prod/kustomization.yaml может выглядеть иначе:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
namePrefix: prod-
namespace: production
labels:
- pairs:
    environment: production
    sre-team: blue
  includeSelectors: true

При запуске kustomize build . в каталоге overlays/dev генерируется development-вариант, а в overlays/prod — production-вариант. И всё это — без внесения каких-либо изменений в исходные файлы, декларативным и детерминированным способом. Базовую конфигурацию и overlay-директории можно коммитить в систему управления версиями, зная, что в любой момент можно воспроизвести нужную конфигурацию.

Что изменилось с 2019 года: краткий обзор

Помимо замены commonLabels на labels, стоит упомянуть несколько ключевых эволюций, которые делают Kustomize более мощным и удобным инструментом в 2026 году:

  • Поле patches заменило устаревшие patchesStrategicMerge и patchesJson6902. Теперь можно применять как стратегические merge-патчи, так и JSON-патчи (JSON 6902) через единое поле, указывая цель патча с помощью селекторов (group, version, kind, name, namespace, labelSelector).
  • Генераторы configMapGenerator и secretGenerator позволяют создавать ConfigMap и Secret из литералов или файлов. Имя сгенерированного ресурса включает хеш содержимого, поэтому при изменении данных Deployment автоматически перезапускается — это особенно удобно для GitOps-сценариев&
  • Поле replicas даёт простой способ изменения количества реплик без написания патчей: достаточно указать имя ресурса и желаемое количество.
  • Поле images позволяет изменять имена образов, теги или дайджесты без редактирования Deployment.
  • Компоненты (components) — механизм переиспользования наборов трансформаций между overlays, который появился уже после выхода оригинальной статьи и снижает дублирование в сложных конфигурациях.
  • Интеграция с Helm через helmCharts (ранее helmChartInflationGenerator) позволяет рендерить Helm-чарты как базу для дальнейшей кастомизации в Kustomize. Это популярный паттерн: Helm используется только для рендеринга сторонних чартов, а Kustomize (часто в связке с Argo CD или Flux) — для применения и управления жизненным циклом ресурсов.

Заключение

Kustomize умеет гораздо больше, чем рассказано в этой статье, но надеюсь, что она послужит хорошим введением. Главная идея осталась неизменной с 2019 года: декларативная кастомизация YAML без шаблонов, с сохранением исходных файлов нетронутыми и возможностью воспроизвести любую конфигурацию в любой момент.

Дополнительные ресурсы

https://kustomize.io/

Похожие записи