Структура Helm-чарта: Полный разбор Chart.yaml, values.yaml и templates | Практическое руководство

Helm-чарт: от пользователя к создателю

Helm — это не просто команда для установки приложений в Kubernetes. Это инструмент управления приложениями, где чарт является его фундаментом. Понимание внутренней структуры чарта — это ключ к переходу от пассивного использования готовых решений к осмысленному созданию и кастомизации. Чарт — это единица управления, которая инкапсулирует версионность, конфигурацию и зависимости вашего приложения.

Цель этого руководства — не просто перечислить файлы, а показать систему, где каждый элемент играет свою роль. К концу статьи у вас будет не только теоретическое понимание, но и ваш собственный минимальный, но полностью рабочий чарт. Это основа для решения любых задач с Helm, от простой установки до создания production-ready развертываний.

Анатомия чарта: разбираем структуру директории

Стандартная структура директории Helm-чарта, созданная командой helm create, выглядит следующим образом:

my-chart/
├── Chart.yaml
├── values.yaml
├── charts/
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── NOTES.txt
│   └── tests/
└── .helmignore

Каждый элемент имеет строгое назначение:

Chart.yaml: Паспорт чарта, содержащий метаданные.
values.yaml: Центральный узел конфигурации, значения по умолчанию.
charts/: Директория для зависимостей (subcharts).
templates/: Сердце чарта — шаблоны манифестов Kubernetes.
.helmignore: Аналог .gitignore, исключает файлы из упаковки чарта.

Chart.yaml: паспорт вашего приложения

Файл Chart.yaml — это не формальность, а критически важные метаданные. Он используется репозиториями для индексации, Helm CLI для управления зависимостями и семантического версионирования.

Ключевые поля:

apiVersion: Версия API Helm (v2 для Helm 2, v1 для Helm 3). Для Helm 3 используйте apiVersion: v2.
name: Имя чарта. Должно быть уникальным в репозитории.
version: Версия чарта по правилам семантического версионирования (например, 1.0.0). Именно эта версия используется для управления релизами.
appVersion: Версия приложения, которое упаковывает чарт (например, 1.21.1 для nginx). Это информационное поле.
description: Краткое описание чарта.
type: Обычно application. Может быть library для чартов-библиотек.

Особое внимание заслуживает секция dependencies. Здесь описываются другие чарты, от которых зависит ваш. Зависимости скачиваются и помещаются в директорию charts/.

# Пример расширенного Chart.yaml
apiVersion: v2
name: my-nginx
version: surveyed
appVersion: "1.21.1"
description: A minimal Nginx deployment chart.
type: application
dependencies:
  - name: redis
    version: "~12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

values.yaml: центральный узел конфигурации

Файл values.yaml — это главный инструмент для кастомизации чарта без правки шаблонов. Он реализует принцип разделения кода (шаблоны) и конфигурации (значения). Пользователь может переопределять эти значения через собственный файл values или флаг --set.

Структура данных — стандартный YAML: словари, списки, простые значения.

# Пример values.yaml с комментариями
# Количество реплик пода
replicaCount: 1

# Настройки образа контейнера
image:
  repository: nginx
  tag: "1.21.1"
  pullPolicy: IfNotPresent

# Настройки сервиса
service:
  type: ClusterIP
  port: 80

# Включение Ingress
ingress:
  enabled: false
  className: "nginx"
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific

Правильно документированный values.yaml с комментариями — признак профессионального чарта, который легко адаптировать под свою среду. Если вы хотите глубже разобраться в инструментах конфигурации в Kubernetes, рекомендуем наше практическое сравнение CRD и ConfigMap.

Директория templates/: где манифесты обретают форму

Файлы в директории templates/ — это не готовые манифесты Kubernetes, а их шаблоны, написанные на языке Go Templates. «Магия» Helm заключается в том, что движок шаблонов подставляет значения из values.yaml и других источников в эти шаблоны, генерируя итоговые YAML-манифесты для применения в кластере.

Типовой набор включает:

deployment.yaml: Шаблон для развертывания (Deployment).
service.yaml: Шаблон для сервиса (Service).
ingress.yaml: Шаблон для входящего трафика (Ingress).
configmap.yaml, secret.yaml: Для конфигураций и секретов.
NOTES.txt: Шаблон для вывода кастомного сообщения после установки.

Ключевые концепции, которые используются в шаблонах:

{{ .Values.replicaCount }} — подстановка значения из файла values.yaml.
{{ .Release.Name }} — имя текущего релиза Helm.
{{ .Chart.Name }} — имя чарта из Chart.yaml.

Создаем свой первый чарт: практика на примере Nginx

Перейдем от теории к практике. Создадим минимальный, но полностью функциональный чарт для развертывания Nginx.

Создаем базовую структуру и чистим лишнее:

helm create my-nginx
cd my-nginx
# Удаляем лишние файлы для чистоты примера
rm -rf templates/*

Редактируем Chart.yaml: Упростим файл, оставив только самое необходимое.
```
apiVersion: v2
name: my-nginx
version: 0.1.0
description: A minimal Nginx Helm chart
type: application
```
Настраиваем values.yaml: Оставим только ключевые параметры для образа Nginx и сервиса.
```
replicaCount: 1

image:
  repository: nginx
  tag: "stable"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80
```
Создаем основные шаблоны: В директории templates/ создадим два файла: deployment.yaml и service.yaml.

Пишем и понимаем шаблоны: от переменных к функциям

Давайте детально разберем синтаксис на примере шаблона deployment.yaml.

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-nginx
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - containerPort: {{ .Values.service.port }}

Разбор элементов:

Подстановки: {{ .Values.replicaCount }} заменится на число 1 из values.yaml.
Конкатенация строк: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" сформирует строку "nginx:stable".
Использование объектов: {{ .Release.Name }} гарантирует уникальность имени развертывания для каждого релиза Helm.

Шаблоны поддерживают управляющие структуры:

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
...
{{- end -}}

И функции с пайплайнами (конвейерами):

# Функция default задает значение по умолчанию, quote — оборачивает в кавычки.
name: {{ .Values.name | default .Chart.Name | quote }}

Для управления сложными приложениями часто требуется оркестрация контейнеров. Если вы рассматриваете альтернативы Kubernetes, вам может быть полезно практическое руководство по Docker Swarm.

Проверка и установка: не нажимаем Enter без проверки

Перед установкой чарта в кластер обязательна его верификация. Это предотвратит ошибки и потенциальные сбои.

Проверка синтаксиса и структуры:
```
helm lint .
```
Команда проверит корректность Chart.yaml и шаблонов.
Рендеринг итоговых манифестов (отладка):
```
helm template . --debug
```
Или с имитацией установки:
```
helm install my-release . --dry-run --debug
```
Эти команды покажут, какие именно YAML-файлы будут отправлены в кластер. Это лучший способ проверить логику подстановок и условных операторов.
Установка в тестовый неймспейс:
```
helm install my-nginx-release . --namespace test-namespace --create-namespace
```
Если все проверки прошли успешно, можно выполнять установку.

От простого к сложному: элементы для поддерживаемых чартов

Минимальный рабочий чарт — это начало. Для создания профессиональных, удобных для командной работы и повторного использования чартов, рекомендуется добавить следующие элементы:

Файлы-помощники (templates/_helpers.tpl): Здесь выносят сложную логику шаблонов и определяют общие метки или функции. Например, определение стандартных лейблов чарта.
```
{{- define "my-nginx.labels" -}}
app: nginx
chart: {{ .Chart.Name }}-{{ .Chart.Version }}
release: {{ .Release.Name }}
{{- end -}}
```
Затем в шаблоне используете {{ include "my-nginx.labels" . }}.
Файл NOTES.txt: Шаблон в templates/NOTES.txt. Его содержимое выводится после успешной установки helm install. Идеально для подсказок пользователю: как получить доступ к приложению, проверить статус.
JSON-схема для values (values.schema.json): Позволяет валидировать файл values.yaml на соответствие структуре и типам данных до рендеринга шаблонов. Защищает от опечаток и некорректных конфигураций.
Файл Chart.lock: Автоматически генерируется командой helm dependency update. Фиксирует точные версии зависимостей, обеспечивая воспроизводимость сборки.
Тесты (templates/tests/): Позволяют определить Pod'ы, которые проверяют работоспособность установленного приложения. Запускаются командой helm test.

Если вы столкнулись с проблемами в работе пользовательских ресурсов (CR), которые часто используются в сложных чартах, вам поможет полное руководство по диагностике Custom Resources.

Итоги: ваш путь от структуры к мастерству

Вы разобрали фундаментальные блоки Helm-чарта:

Chart.yaml — метаданные и зависимости.
values.yaml — централизованная конфигурация.
templates/ — логика генерации манифестов на основе конфигурации.

Вы освоили принцип разделения кода (шаблоны) и конфигурации (values), который лежит в основе гибкости Helm. Вы научились обязательной практике проверки чарта с помощью helm lint и helm template --debug перед установкой в кластер.

Для дальнейшего развития рекомендуется:

Изучить официальную документацию по функциям и пайплайнам шаблонов Helm.
Анализировать структуру чартов из популярных репозиториев (например, bitnami).
Практиковаться в упаковке своих собственных приложений, начиная с простых и постепенно добавляя элементы для поддерживаемости (_helpers.tpl, схему валидации).

Понимание внутренней структуры — это основа, которая позволяет уверенно читать, модифицировать и создавать Helm-чарты для эффективного управления приложениями в Kubernetes.