Конфигурация в 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 }}" }
    }

Проблемы:

  1. У сервиса средней сложности в values.yaml набирается 40+ ключей.
  2. Многострочные значения в YAML - это боль (отступы, экранирование).
  3. Внутри values нельзя использовать условия (if eq $env "Production").
  4. Секреты лежат открытым текстом в 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 }}

Как это работает:

  1. include (print $.Template.BasePath "/configmap.yaml") . рендерит шаблон ConfigMap в строку.
  2. sha256sum хеширует её.
  3. Хеш записывается в аннотацию Pod template.
  4. Секреты в 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