Kustomize: генератор ConfigMap

ConfigMap - это объект Kubernetes, который хранит конфигурацию приложения в виде пар ключ-значение. Обычно его пишут отдельным YAML-файлом. Kustomize предлагает второй путь: описать данные прямо в kustomization.yaml, а объект пусть собирается при рендере.

Три источника данных

configMapGenerator умеет брать данные из трёх мест.

literals - пары КЛЮЧ=значение списком прямо в конфигурации:

configMapGenerator:
  - name: app-config
    literals:
      - APP_COLOR=blue
      - APP_MODE=prod

files - содержимое файла целиком. Ключом становится имя файла, значением весь его текст. Так удобно класть в ConfigMap конфиги целиком:

configMapGenerator:
  - name: nginx-config
    files:
      - nginx.conf
      - default.conf=configs/site.conf

Вторая строка показывает переименование: ключ будет default.conf, а содержимое возьмётся из configs/site.conf.

envs - файл в формате КЛЮЧ=значение, где каждая строка становится отдельным ключом ConfigMap. Разница с files принципиальная: files кладёт весь файл под один ключ, envs разбирает файл построчно.

configMapGenerator:
  - name: app-env
    envs:
      - app.env

Источники комбинируются: в одном генераторе могут быть и literals, и files.

Источник	Что попадает в ConfigMap	Чем становится ключ
literals	пары прямо из kustomization.yaml	часть строки до =
files	весь файл одним значением	имя файла
envs	каждая строка файла отдельно	ключ из строки файла

Хеш-суффикс

К имени сгенерированного объекта Kustomize дописывает хеш содержимого: app-config-2g7h5k6t9b. Изменилось значение - изменился хеш, а с ним и имя.

Сделано это ради перезапуска Pod. Deployment ссылается на ConfigMap по имени. Пока имя постоянное, правка данных для Deployment невидима: spec.template не изменился, значит rollout не запускается, и работающие Pod продолжают читать старые значения, пока их кто-нибудь не перезапустит руками.

С хеш-суффиксом всё складывается само. Kustomize меняет имя объекта и заодно правит ссылку на него внутри Deployment. Pod-шаблон меняется, кластер видит новую ревизию и катит обновление.

Иногда суффикс мешает: на ConfigMap ссылаются извне по фиксированному имени, или его читает сторонний контроллер. Тогда суффикс отключают:

generatorOptions:
  disableNameSuffixHash: true

Тот же блок умеет вешать общие labels и annotations на все генерируемые объекты.

Переопределение в overlay

Генератор из base можно доработать в overlay через поле behavior:

# overlays/prod/kustomization.yaml
configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - APP_MODE=production

merge добавляет и перезаписывает ключи поверх генератора из base. replace заменяет содержимое целиком. create (значение по умолчанию) создаёт новый объект. Для merge и replace в base обязан быть генератор с таким же именем, иначе Kustomize сообщит, что цель слияния не найдена.

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

Старые версии ConfigMap не убираются сами. Каждая правка порождает новое имя, прежний объект остаётся в namespace навсегда. Со временем kubectl get cm показывает десяток app-config-*. Чистят их через prune в GitOps-инструменте или руками.

literals не место для паролей. Содержимое kustomization.yaml лежит в git открытым текстом, и ConfigMap по определению не считается секретом.

Значения с пробелами или спецсимволами в literals требуют кавычек по правилам YAML: - GREETING="hello world". Без кавычек YAML-парсер разберёт строку не так, как вы ожидали.

Проверить результат до применения помогает всё тот же рендер:

kubectl kustomize . | grep -A5 'kind: ConfigMap'

Домашка

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

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

Коротко

• configMapGenerator собирает ConfigMap из literals, files или envs без отдельного YAML-файла.
• files кладёт весь файл под один ключ, envs разбирает файл построчно на отдельные ключи.
• Хеш в имени меняется вместе с данными и запускает rollout Pod, потому что Kustomize правит и ссылку в Deployment.
• generatorOptions.disableNameSuffixHash: true отключает суффикс, если на имя ссылаются извне.
• В overlay генератор дорабатывается через behavior: merge или replace.