Конфигурация в Helm-чарте: Files.Get, tpl и директория config/
Published: 2026-05-25
У Helm есть два способа передать в чарт внешнее содержимое: values.yaml и .Files.Get. Для конфигов приложений (appsettings.json, nginx.conf, log4j.properties) Files.Get подходит гораздо лучше, чем многострочные простыни в values. В этом посте схема, к которой мы пришли после выкатки ~60 .NET-микросервисов. Конфиг лежит в config/ в виде файлов-шаблонов, секреты рендерятся в CI. Потом файлы попадают в ConfigMap через Files.Get, а checksum-аннотации принудительно запускают rolling restart.
Чем плох values.yaml для конфигов
Очень хочется положить конфиг прямо в values.yaml:
yaml# Так не делать
config:
connectionString: "Server=db;Database=app;User=app;Password=secret"
rabbitHost: "rabbit.infra"
Затем в шаблоне:
yamldata:
appsettings.json: |
{
"ConnectionStrings": { "Default": "{{ .Values.config.connectionString }}" },
"RabbitMq": { "Host": "{{ .Values.config.rabbitHost }}" }
}
Проблемы:
- У сервиса средней сложности в
values.yamlнабирается 40+ ключей. - Многострочные значения в YAML - это боль (отступы, экранирование).
- Внутри values нельзя использовать условия (
if eq $env "Production"). - Секреты лежат открытым текстом в
values-Production.yaml.
Схема с Files.Get
Вместо этого мы храним appsettings.json как обычный JSON-файл в config/:
my-service/
config/
appsettings.json ← рендерится consul-template при деплое
appsettings.ENV.json ← переопределения для среды, тоже рендерятся
crt/
YC-CA.pem ← CA-сертификат, рендерится из Vault
files/
config.hcl ← источник consul-template для appsettings.json
config-user.hcl ← источник для appsettings.ENV.json
config-crt.hcl ← источник для YC-CA.pem
Шаблон configmap.yaml загружает отрендеренные файлы через Files.Get:
yamlapiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "my-service.fullname" . }}-app-settings
data:
appsettings.json: |
{{ tpl (.Files.Get "config/appsettings.json") . | indent 4 }}
appsettings.{{ .Values.aspnetcoreEnvironment }}.json: |
{{ tpl (.Files.Get "config/appsettings.ENV.json") . | indent 4 }}
Обратите внимание на tpl вокруг .Files.Get. Он прогоняет содержимое файла через шаблонизатор Helm, поэтому внутри JSON можно ссылаться на {{ .Values.* }}. Так удобно подставлять в конфиг, например, {{ .Values.replicaCount }} или {{ .Release.Namespace }}.
Почему indent 4, а не nindent
indent 4 добавляет 4 пробела в начало каждой строки. nindent 4 сначала добавляет перенос строки, а потом 4 пробела. Для блочного скаляра YAML (|) правильный вариант indent: у первой строки должен быть тот же отступ, что и у остальных.
С nindent в начале значения появляется лишняя пустая строка. Большинству парсеров всё равно, но в kubectl get cm -o yaml это выглядит криво.
ConfigMap с CA-сертификатом
CA PEM лежит в отдельном ConfigMap, чтобы его можно было обновлять отдельно от остального:
yamlapiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "my-service.fullname" . }}-ca-pemstore
data:
YC-CA.pem: |
{{ .Files.Get "crt/YC-CA.pem" | indent 4 }}
Здесь tpl не нужен: PEM - обычный текст, а не шаблон.
volumeMounts в Deployment
Оба ConfigMap монтируются в контейнер ровно по тем путям, где их ждёт .NET runtime:
yamlvolumeMounts:
- name: config
mountPath: /app/appsettings.json
subPath: appsettings.json
- name: config
mountPath: /app/appsettings.{{ .Values.aspnetcoreEnvironment }}.json
subPath: appsettings.{{ .Values.aspnetcoreEnvironment }}.json
- name: ca-pemstore
mountPath: /etc/ssl/certs/YC-CA.pem
subPath: YC-CA.pem
readOnly: true
volumes:
- name: config
configMap:
name: {{ include "my-service.fullname" . }}-app-settings
- name: ca-pemstore
configMap:
name: {{ include "my-service.fullname" . }}-ca-pemstore
subPath монтирует один ключ из ConfigMap как отдельный файл и не заменяет всю директорию. Без subPath монтирование в /app скрыло бы все остальные файлы в /app.
Принудительный rolling restart при изменении конфига
Deployment хранит хеш каждого ConfigMap в .spec.template.metadata.annotations:
yamlmetadata:
annotations:
checksum/configmap: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
checksum/configmap-ca: {{ include (print $.Template.BasePath "/capem-configmap.yaml") . | sha256sum }}
Как это работает:
include (print $.Template.BasePath "/configmap.yaml") .рендерит шаблон ConfigMap в строку.sha256sumхеширует её.- Хеш записывается в аннотацию Pod template.
- Секреты в Vault поменялись, пайплайн заново отрендерил
config/appsettings.json. Меняется содержимое ConfigMap, следом хеш и спецификация Pod template, и Kubernetes сам запускает rolling update.
Без этой аннотации helm upgrade обновил бы ConfigMap, но запущенные поды продолжили бы работать со старым конфигом в памяти. Kubernetes не перезапускает поды, когда меняется примонтированный ConfigMap. А файлы, смонтированные через subPath, вообще не обновляются.
Заглушка ENV в имени файла
В имени файла appsettings.ENV.json стоит буквально строка ENV. Так и в git, и в пути, куда пишет consul-template при вызове consul-template -once в CI:
bashconsul-template \
-template="chart/files/config-user.hcl:chart/config/appsettings.ENV.json" \
-once
То есть ENV остаётся как есть. Настоящее имя среды (Development, Production и т.д.) приходит при деплое через --set aspnetcoreEnvironment=${APP_ENV}. Шаблон configmap называет ключ по {{ .Values.aspnetcoreEnvironment }}, поэтому в рантайме контейнер получает /app/appsettings.Production.json.
Helm lint
helm lint проверяет шаблоны чарта. config/appsettings.json добавлен в .gitignore (это результат рендеринга), поэтому, чтобы lint проходил, нужен файл-заглушка:
json{}
Закоммитьте эту заглушку как config/appsettings.json. При деплое consul-template её перезапишет. helm lint и локальный helm template увидят пустой, зато валидный JSON-объект.
Итог
| Задача | Решение |
|---|---|
| Секреты в конфиге | consul-template рендерит их из Vault до helm upgrade |
| Формат конфига | Обычный JSON/YAML в config/, а не внутри values.yaml |
| Доступ из Helm-шаблона | Files.Get, при необходимости с tpl |
| Монтирование в под | Отдельный subPath volumeMount для каждого файла |
| Rolling update при изменении | Аннотация checksum/* в Pod template |
| Локальные lint/template | Файлы-заглушки в config/ в git |