ConfigMap в Kubernetes — практическое руководство

Логотип Kubernetes

Быстрые ссылки

Для чего нужны ConfigMap?
Когда их не использовать
Создание ConfigMap
Связывание ConfigMap и Pod
Выборочное добавление переменных окружения
Использование ConfigMap как тома
Обновление значений ConfigMap
Неизменяемые ConfigMap
Дополнительно: практики, чек‑листы и ликбез

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

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

Ключевые особенности в одной строке:

ConfigMap — ресурс API Kubernetes для небезопасных строковых настроек.
Доступ к значениям возможен как через переменные окружения или файлы внутри смонтированного тома.

Когда их не использовать

Важно: не храните в ConfigMap конфиденциальные данные. ConfigMap не шифруются и не защищены так, как Secrets. Никогда не кладите пароли, токены или приватные ключи в ConfigMap — для этого есть Kubernetes Secret.

Ограничения и подходы:

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

Противопоказания и альтернативы:

Большие конфигурационные файлы: лучше монтировать готовый файл через том инициализатора или смонтировать ConfigMap, содержащий один текстовый файл.
Секреты и учетные данные: используйте Secret.
Частые динамические конфигурации на уровне приложения: рассмотрите систему конфигурации (например, Consul) вместо ConfigMap.

Создание ConfigMap

ConfigMap описывается простым YAML-манифестом. Обязательны metadata.name и поле data с парами ключ=значение.

Пример простого ConfigMap:

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

Пояснения:

Поле data — для строковых значений.
Поле binaryData — для base64-кодированных бинарных значений; ключи должны быть уникальны между data и binaryData.

Применение манифеста выполняется командой kubectl apply -f <файл>.yaml или через любой GitOps/CI инструмент.

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

ConfigMap сам по себе ничего не делает, пока вы не свяжете его с Pod. Ниже пример Pod, который импортирует все ключи ConfigMap как переменные окружения:

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

envFrom импортирует все пары ключ=значение из указанного ConfigMap. Контейнеры внутри Pod получат переменные окружения database_host и system_email.

Выборочное добавление переменных окружения

Если нужен более тонкий контроль или переименование переменных, используйте секцию env и ссылку configMapKeyRef:

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

В этом примере из ConfigMap берётся только ключ database_host, и он передаётся в Pod как переменная DATABASE_HOST_IP.

Советы:

Избегайте конфликтов имён переменных: явно определяйте имена в env.
Для критичных значений добавляйте проверки при старте контейнера — валидируйте переменные окружения.

Использование ConfigMap как тома

ConfigMap можно монтировать в Pod как файловый том. Kubernetes создаст файлы, соответствующие ключам 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

Результат:

Каждый ключ ConfigMap становится файлом в /etc/config-data.
Приложение может читать файлы как обычные конфигурационные файлы.

Когда использовать томы:

Когда приложение ожидает файловую конфигурацию.
Когда значения — большие текстовые блоки (вплоть до лимита 1 МБ).

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

ConfigMap можно изменять в любое время — это обычный ресурс API. Поведение при обновлении зависит от механизма инъекции.

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

Kubernetes периодически проверяет изменения ConfigMap и обновляет файлы в смонтированном томе. Это происходит автоматически, но с задержкой, зависящей от настроек Kubelet на нодах. Приложение должно уметь безопасно перечитывать файл или реагировать на обновления.

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

Переменные окружения

Значения переменных окружения фиксируются при создании контейнера. Изменение ConfigMap не обновит уже запущенные Pods, если вы используете envFrom или env->configMapKeyRef. Чтобы новые значения начали работать, нужно пересоздать Pod (например, обновить Deployment или изменить аннотацию, чтобы триггернуть перезапуск).

Как принудительно обновить конфигурацию:

Обновить Deployment (изменить образ или аннотацию) — это приведёт к обновлению Pods.
Выполнить rollout restart: kubectl rollout restart deployment/<имя>.

Неизменяемые ConfigMap

ConfigMap поддерживают опцию immutable: true. После установки этой опции данные ConfigMap нельзя изменить или вернуть обратно в изменяемое состояние.

Пример:

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

Зачем это нужно:

Защита от случайных изменений.
Меньшая нагрузка на систему распространения конфигурации (Kubernetes меньше отслеживает изменения).

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

Практические рекомендации и шаблоны

Мини‑методология развёртывания конфигураций:

Храните только небезопасные строки в ConfigMap. Секреты — в Secret.
Разделяйте конфигурацию по областям ответственности (сеть, логирование, фичи). Мульти‑ConfigMap уменьшает поверхность изменений.
Для переменных окружения используйте env с configMapKeyRef, если нужно контрольное переименование и фильтрация.
Для файловой конфигурации монтируйте ConfigMap как том.
Для безопасного обновления внедряйте процесс: создать новую версию ConfigMap → обновить Deployment/StatefulSet → мониторить.

Ролевая чек‑листа (DevOps / разработчик):

DevOps:
- Убедиться, что ConfigMap не содержит секретов.
- Настроить CI/CD для применения манифестов в контролируемом порядке.
- Настроить политику имён для версий конфигураций.
Разработчик:
- Проверить, что приложение корректно обрабатывает отсутствие ключей.
- Добавить в стартер логирование принятых конфигураций.

Критерии приёмки для изменения ConfigMap:

Конфигурация проверена в тестовой среде.
Deployment автоматически обновлён и прошёл health‑checks.
Rollback-план задокументирован.

Контрольные примеры, когда ConfigMap не подойдёт:

Требуется шифрование на уровне хранилища. Решение: Secrets или внешняя KMS/Secret Manager.
Необходима синхронизация конфигурации в реальном времени между сервисами. Решение: конфигурационный брокер (Consul, etcd, Spring Cloud Config и т.п.).

Дополнительная справка: модель принятия решения

Mermaid-диаграмма для выбора между ConfigMap и Secret:

flowchart TD
  A[Нужно ли хранить конфиденциальные данные?] -->|Да| B[Использовать Secret]
  A -->|Нет| C[Изменяется ли часто конфигурация?
  'реальное время?']
  C -->|Да| D[Рассмотреть внешний конфиг-сервис]
  C -->|Нет| E[Использовать ConfigMap 'env или том']

Безопасность, соответствие и локальные особенности

Конфиденциальность: ConfigMap не шифруются — при необходимости применяйте Secrets и, при желании, интегрируйте с KMS для шифрования на уровне и кластерного хранилища.
GDPR/личные данные: не храните персональные данные в ConfigMap.
В локальных средах (например, разработки в компании) убедитесь, что RBAC ограничивает доступ к пространству имён и ресурсам.

Миграция и совместимость

При переносе приложения между кластерами убедитесь, что:

Имена ConfigMap совпадают или механизмы CI/CD создают нужные ресурсы.
Если вы используете immutable ConfigMap, планируйте версионирование имён.

Совместимость с инструментами:

GitOps (ArgoCD, Flux) отлично подходят для хранения ConfigMap как инфраструктурного кода.
Helm позволяет шаблонизировать ConfigMap и версионировать значения через chart values.

Краткий словарь (1‑строчно)

ConfigMap — ресурс Kubernetes для небезопасных конфигурационных пар ключ=значение.
Secret — ресурс для хранения конфиденциальных данных (шифрование/особые права).
envFrom/env — способы инъекции переменных окружения из ConfigMap.
volumeMount/configMap — монтирование ConfigMap как набора файлов в Pod.

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

ConfigMap — удобный инструмент для управления небезопасной конфигурацией в Kubernetes. Используйте их для строковых параметров, монтируйте как томы для файлов и применяйте env/envFrom для переменных окружения. Для секретов используйте Kubernetes Secrets. Планируйте версионирование, тестируйте обновления и документируйте процесс отката.

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

ConfigMap в Kubernetes: руководство по использованию