ConfigMap в Kubernetes — руководство

Логотип Kubernetes на фоне белого поля

ConfigMap — это ресурс Kubernetes для передачи ненесекретной конфигурации в контейнеры. Используйте его для строковых пар ключ-значение или как файлы в томах. Не храните в ConfigMap пароли и ключи — для этого есть Secrets. Mount-томы автоматически обновляются при изменении ConfigMap, а переменные окружения — нет; для их обновления нужно пересоздать Pod.

О чём этот материал

Этот текст объясняет, для чего нужны ConfigMap, как их создавать и связывать с Pod, какие есть ограничения и когда лучше выбрать альтернативы. Приведены практические шаблоны YAML, чек-листы, критерии приёмки и runbook для обновления конфигурации.

Для чего нужны ConfigMap

ConfigMap предназначены для хранения небольших объёмов ненесекретной конфигурации. Это способ передать произвольные пары ключ-значение в Pod, не зашивая значения в образ контейнера. Типичные примеры:

адресы баз данных или сервисов;
адреса отправителя почты приложения;
флаги включения/отключения функций;
небольшие файлы конфигурации, разбитые по ключам.

Короткая дефиниция: ConfigMap — ресурс Kubernetes для управления ненесекретными параметрами, доступными контейнерам в виде переменных окружения или файлов в смонтированном томе.

Чего не следует хранить в ConfigMap

Секреты: пароли, API-ключи, приватные ключи. Для них используйте Kubernetes Secret.
Большие файлы и двоичные объекты, общий размер одного ConfigMap не должен превышать 1 МБ.
Данных, требующих шифрования или строгого контроля доступа.

Важно: значения в ConfigMap не шифруются и видны любому, у кого есть права на чтение ресурса в кластере.

Если конфигурация превышает лимит или содержит чувствительные данные, рассмотрите альтернативы: Secrets, внешний конфиг-сервис, монтирование конфигурационных файлов через CSI или init-контейнер, который загружает конфиг из защищённого хранилища.

Ограничения формата

Значения в поле data — строки в UTF-8. Для двоичных данных используйте binaryData с base64-кодированием.
Имена ключей могут содержать буквы, цифры, точки (.), дефисы (-) и подчёркивания (_).
Общий размер одного ConfigMap (включая все ключи/значения) ограничен 1 МБ.

Создание ConfigMap

Минимальный YAML для ConfigMap выглядит так:

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-configmap
data:
  database_host: "192.168.0.10"
  system_email: "k8s@example.com"

Если у вас есть двоичные данные, используйте binaryData:

apiVersion: v1
kind: ConfigMap
metadata:
  name: binary-configmap
binaryData:
  archive.tar.gz: H4sIAAAAAAAA/...

Примените манифест командой:

kubectl apply -f configmap.yaml

Или используйте kubectl create configmap для быстрого создания из файла или переменных окружения.

Связывание ConfigMap с Pod

ConfigMap не действует сам по себе — его нужно подключить к Pod. Есть два основных способа: через переменные окружения и через смонтированный том.

Переменные окружения (envFrom и env)

Быстрый способ подтянуть все ключи ConfigMap в контейнер:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: example-container
    image: example-image:latest
    envFrom:
    - configMapRef:
        name: example-configmap

Если нужно взять только отдельные ключи и/или переименовать их, используйте valueFrom и configMapKeyRef:

env:
- name: DATABASE_HOST_IP
  valueFrom:
    configMapKeyRef:
      name: example-configmap
      key: database_host

Заметьте: переменные окружения захватываются при создании контейнера. Обновления ConfigMap не повлияют на уже запущенные Pod.

Смонтированные тома

ConfigMap можно смонтировать как файловую систему. Каждый ключ превратится в файл с именем ключа и содержимым — в значение:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: example-container
    image: example-image:latest
    volumeMounts:
    - name: app-config
      mountPath: "/etc/config-data"
      readOnly: true
  volumes:
  - name: app-config
    configMap:
      name: example-configmap

Файлы в /etc/config-data будут обновляться автоматически при изменении ConfigMap (с учётом задержки, зависящей от kubelet).

Обновление значений ConfigMap

Если ConfigMap обновлён, Pod, который использует его как том, увидит обновления (kubelet периодически синхронизирует файлы в томе).
Если ConfigMap используется для переменных окружения, уже запущенные Pod не получат обновления. Требуется пересоздать Pod (например, rollout restart Deployment) или изменить аннотацию для форсированного пересоздания.

Практический приём: помечайте Deployment аннотациями с версией конфига. При изменении ConfigMap меняйте аннотацию, чтобы инициировать rolling update.

Immutable ConfigMap

Если вы уверены, что набор значений никогда не изменится, можно сделать ConfigMap immutable:

apiVersion: v1
kind: ConfigMap
metadata:
  name: immutable-configmap
data:
  foo: bar
immutable: true

Преимущества:

Запрещает случайные изменения.
Снижает накладные расходы на синхронизацию изменений.

Ограничение: после установки immutable true вы не сможете изменить данные в этом ресурсе (нужно создать новый ConfigMap).

Когда ConfigMap не подходит — варианты и альтернативы

Если конфигурация чувствительна — используйте Secret.
Если нужен крупный статический файл конфигурации (>1 МБ) — храните файл в образе, используйте PersistentVolume или CSI-провайдер для доставки большого файла.
Если конфиг должен централизованно управляться и иметь версии — используйте внешние решения (Consul, Vault, Spring Cloud Config) и инициализируйте Pod через init-контейнер.

Краткое правило: ConfigMap хорош для небольших, ненесекретных и часто читаемых приложениям настроек.

Ментальные модели и эвристики

Разделение обязанностей: адреса и ‘нечувствительные’ флаги в ConfigMap; секреты в Secret; большие файлы в PV или внешнем хранилище.
Минимизация прав: предоставляйте каждому Pod только те ключи, которые ему нужны (env, а не envFrom).
Версионирование: не изменяйте критичные настройки на лету — создавайте новую версию ConfigMap и применяйте в новых Deployment rollout.

Факто-бокс — ключевые цифры и факты

Максимальный размер одного ConfigMap: ~1 МБ.
Форматы значений: data — UTF-8 строки; binaryData — base64.
Механизмы потребления: env/envFrom (переменные окружения), volume (файлы).

Шаблоны и сниппеты (cheat sheet)

Простой ConfigMap из файлов напрямую:

kubectl create configmap app-config --from-file=./config/

Создать ConfigMap из literal-пар:

kubectl create configmap example --from-literal=database_host=192.168.0.10 --from-literal=system_email=k8s@example.com

Команда для просмотра и отладки:

kubectl describe configmap example-configmap
kubectl get configmap example-configmap -o yaml

Чек-лист для ролей

Разработчик:

Не хранить секреты в ConfigMap.
Проверить имена ключей на соответствие приложению.
Предпочесть env для простых переменных.

SRE / оператор:

Настроить RBAC, чтобы ограничить доступ к чтению ConfigMap.
Использовать immutable для критичных конфигов.
Автоматизировать rollout при обновлении конфигурации.

Security engineer:

Просмотреть все ConfigMap на предмет утечек чувствительных данных.
Проверить журналы аудита доступа к ресурсам.

Критерии приёмки

Поддерживаемое приложение читает значения из ConfigMap через ожидаемый способ (env или том).
При обновлении ConfigMap и использовании тома новые значения отражаются в контейнере в разумное время.
Для переменных окружения обновление приводит к успешному rolling update Deployment.
Все секретные данные вынесены в Secrets и не присутствуют в ConfigMap.

Runbook: как безопасно обновить конфигурацию

Подготовьте новую версию ConfigMap с явной версией в имени (например, example-configmap-v2) или измените аннотацию.
Примените ConfigMap: kubectl apply -f new-configmap.yaml.
Для Deployment: kubectl rollout restart deployment/my-app или обновите аннотацию pod template.
Наблюдайте за rollout: kubectl rollout status deployment/my-app.
При проблемах — откат: kubectl rollout undo deployment/my-app.

Примечание: если вы используете mounted-томы, можно сначала протестировать обновление в staging — kubelet может занять несколько секунд или минут для синхронизации.

Decision flow — выбрать ConfigMap или альтернативу

flowchart TD
  A[Нужно передать конфиг в Pod?] --> B{Содержит ли конфиг секреты?}
  B -- Да --> C[Используйте Secret]
  B -- Нет --> D{Размер < 1 МБ?}
  D -- Нет --> E[Используйте PV/CSI или внешний конфиг сервис]
  D -- Да --> F{Нужно обновлять на лету без перезапуска?}
  F -- Да --> G[Используйте ConfigMap + mount volume]
  F -- Нет --> H[Можно использовать env или ConfigMap + volume]

Примеры ошибок и когда это провалится

Ошибка: положили API-ключ в ConfigMap — приводит к утечке при доступе к ресурсу.
Ошибка: попытка хранить большой бинарный файл в data — выйдете за лимит 1 МБ.
Ошибка: используете envFrom и у вас конфликт имён переменных — приложение может получить неверные значения.

Как избежать: ревью конфигов, автоматические сканеры на предмет секретов, ограничение прав доступа.

Локальные рекомендации для российского контекста

При использовании внешних сервисов аутентификации (например, корпоративный Vault) согласуйте политику хранения секретов с командой безопасности.
Для коммерческих кластеров с ограничениями на хранение данных следите за политиками резервного копирования и шифрования at-rest для etcd.

Краткое резюме

ConfigMap — удобный и встроенный инструмент Kubernetes для ненесекретной конфигурации. Используйте переменные окружения для простоты и тома для возможности горячих обновлений. Разделяйте конфигурацию и секреты. Контролируйте доступ и применяйте практики версионирования и тестирования при обновлениях.

Ключевые рекомендации:

Не храните секреты в ConfigMap.
Монтируйте том, если нужно динамическое обновление.
Используйте immutable для неизменяемых данных.
Делайте ревью всех ConfigMap как часть CI/CD.

Если нужно, могу подготовить готовые шаблоны для вашего Deployment, Helm-чарты или инструкции по миграции конфигурации из образа в ConfigMap/Secret.

ConfigMap в Kubernetes — полное руководство