devops-курс Все курсы

✻ Урок 5.9 · Тема 5: Kubernetes и Helm

Helm: упаковываем «Заметки» в чарт

⏱ 4 ч

Как работать с кодом и когда идти дальше

Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:

  • Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
  • Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
  • Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.

Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.

Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.

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

К этому уроку приложение «Заметки» живёт в четырёх отдельных файлах-манифестах: Deployment, Service, ConfigMap и HTTPRoute. Манифест (manifest) это YAML-файл с описанием объекта Kubernetes: «вот такой Deployment, вот столько реплик, вот такой образ». Ты писал их в уроках 5.2, 5.3, 5.4 и 5.6.

Теперь представь, что нужно второе окружение, например dev рядом с prod. Самый простой путь: скопировать файлы и поправить три строки (хост, число реплик, тег образа):

prod/deployment.yaml:   хост notes.lab       реплик 3   образ 0.4.1
dev/deployment.yaml:    хост dev.notes.lab   реплик 1   образ 0.4.1

Через месяц копий будет три, правки разойдутся, и никто не вспомнит, чем prod отличается от dev намеренно, а чем случайно. Helm (по-русски «штурвал»; это программа, которая собирает YAML из шаблонов и отправляет его в кластер) решает это так: манифест превращается в шаблон (template) с пропусками, как дашборд Grafana с переменной $server вместо жёстко записанного имени сервера, а значения пропусков лежат в отдельном маленьком файле. Тег образа (image tag) это метка версии у образа контейнера, например 0.4.1: по ней кластер понимает, какую именно сборку приложения запускать (подробно в уроке 6.3 и дальше по курсу).

Второе, что даёт Helm и чего нет у kubectl apply: история установок и откат одной командой. Откат (rollback) это возврат к предыдущей рабочей версии, как «отменить» в редакторе: без него после неудачного выпуска ты в панике ищешь вчерашние файлы. Выкатил плохую версию, набрал helm rollback, и через минуту всё как было.

На работе Helm встречается каждый день. Почти всё чужое ставится готовыми чартами (chart, то есть готовыми «пакетами» Helm с шаблонами внутри): метрики кластера, мониторинг, почтовые и прочие сервисы. Свои сервисы команды тоже упаковывают в чарты, чтобы деплоить одинаково. В задании 6 ты поставишь чужой чарт сам.

Шаг проекта: приложение «Заметки» переезжает в чарт helm/notes версии 0.1.0, релиз notes ставится в namespace notes, а старые манифесты приложения удаляются из k8s/base/.

Что нужно знать

  • Урок 5.2: Pod и Deployment: чарт генерирует Deployment, нужно понимать его поля (replicas, selector, template).
  • Урок 5.3: Service и DNS: Service notes находит поды по меткам (labels, пары «ключ: значение» на объекте), метки понадобятся в хелперах. Хелпер (helper) это кусок шаблона, который записан один раз и вызывается по имени из других шаблонов, как функция; разберём ниже.
  • Урок 5.4: Вход в кластер: Gateway notes-gw и HTTPRoute, который мы упакуем в чарт.
  • Урок 5.6: ConfigMap и Secret: ConfigMap notes-config переезжает в чарт, а Secret notes-db остаётся снаружи.
  • Урок 5.7: Пробы, ресурсы, rolling update: пробы и ресурсы переезжают в шаблон. Rolling update это постепенная замена старых подов новыми без остановки сервиса: сначала поднимается новый, потом гасится старый.
  • Урок 5.8: Job, CronJob, DaemonSet: CronJob бэкапа остаётся платформенным манифестом.

Картина целиком

Helm работает как шаблон хоста в Zabbix или дашборд Grafana с переменными: общая заготовка одна, а значения (какой сервер, какое окружение) подставляются отдельно. Заготовку можно использовать сотни раз.

  • Чарт (chart) это заготовка: каталог с шаблонами манифестов.
  • Values (значения) это то, что подставляется в пропуски: файл values.yaml.
  • Релиз (release) это чарт, установленный в кластер под именем.
  • Ревизия (revision) это номер версии релиза: каждое обновление даёт новую.

Вот весь путь от файлов до кластера:

flowchart LR
    subgraph M["твоя машина: helm/notes/"]
        CH["Chart.yaml"]
        V["values.yaml<br>values-dev.yaml"]
        T["templates/<br>deployment, service, ..."]
    end
    V --> R
    T --> R
    R["рендер: шаблоны + значения<br>= обычный YAML (в памяти)<br>команда helm upgrade --install"] -->|"YAML"| API["API-сервер кластера<br>создаёт Deployment, Service, ..."]
    R -->|"записывает «ревизия 1»"| S["Secret<br>sh.helm.release.v1.notes.v1"]

Главное, что нужно запомнить: Helm работает на твоей машине. Он берёт шаблоны, подставляет значения (это называется рендер, render: «отрисовать» готовый документ из бланка), получает обычный YAML и отправляет его в API-сервер (API server, «приёмная» кластера, через которую проходят все команды, урок 5.1), как это сделал бы kubectl apply. Отдельной программы Helm внутри кластера нет. Запись «в кластере установлена ревизия 1» лежит в обычном Secret.

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

Теория

Зачем нужен Helm: проблема копий

Kubernetes принимает только готовый YAML, в нём нет ни переменных, ни условий. Для одного окружения это нормально. Для двух начинается копирование файлов, а копии живут отдельной жизнью: в одну внесли исправление, в другую забыли. К тому же у kubectl apply нет памяти: он не знает, что ты применял вчера, и не умеет вернуться назад.

Шаблон с пропусками решает проблему копий: исправил один раз, и все окружения получили исправление. Но шаблон сам ничего не отправляет: в кластер его ставит, записывает в журнал и при ошибке отзывает уже Helm как программа.

Helm делает четыре вещи:

  1. Шаблонизация: подставляет значения в шаблоны.
  2. Упаковка: собирает шаблоны и значения по умолчанию в один каталог-чарт, который можно положить в реестр и поставить в другом кластере.
  3. Учёт: запоминает, что и с какими значениями установлено (релиз и его ревизии).
  4. Откат: возвращает состояние любой прошлой ревизии.

Хост приложения notes.lab в манифесте HTTPRoute написан прямо в файле. Чтобы для dev он был dev.notes.lab, без Helm пришлось бы держать два файла. С Helm в шаблоне стоит пропуск, а значение задаётся при установке: --set gateway.host=dev.notes.lab. Файл шаблона один.

Helm часто называют «менеджером пакетов Kubernetes», но в кластере он ничего не запускает: только формирует YAML и отправляет его в API-сервер, дальше всё делает сам Kubernetes. Если удалить helm с ноутбука, поды и Service продолжат жить; пропадёт удобство управления релизом (обновление и откат), а программу можно поставить снова.

Главное: Helm работает на твоей машине: рендерит шаблоны в YAML и отправляет его в API-сервер, а внутри кластера отдельной программы нет.

Чтобы шаблоны можно было хранить и передавать, их складывают в чарт.

Чарт: что внутри каталога

Шаблоны нужно где-то хранить и как-то передавать другим людям. Чарт (chart) это договорённость о структуре каталога: Helm знает, где искать шаблоны, значения и описание пакета. Без такой договорённости у каждой команды были бы свои папки и свои скрипты сборки.

В чарте три части: паспорт (Chart.yaml), значения по умолчанию (values.yaml) и шаблоны манифестов (templates/). Любое значение можно поменять при установке, не трогая сам чарт.

Для «Заметок» получится такое дерево:

helm/notes/
├── Chart.yaml            паспорт чарта: имя, версия чарта, версия приложения
├── values.yaml           значения по умолчанию (то, что вписывается в пропуски)
├── values-dev.yaml       значения для окружения dev, переопределяют часть умолчаний
└── templates/            шаблоны манифестов
    ├── _helpers.tpl      общие «кусочки» для повторного использования (не манифест)
    ├── configmap.yaml
    ├── deployment.yaml
    ├── service.yaml
    └── httproute.yaml

Каждый файл:

  • Chart.yaml обязателен (без него Helm не признает каталог чартом). В нём apiVersion: v2 (формат чарта, актуальный для Helm 3 и 4), name (имя чарта), version (версия самого чарта) и appVersion (версия приложения, о разнице ниже).
  • values.yaml есть почти в каждом чарте, но Helm его не требует: чарт без него ставится. Здесь лежат все настройки с разумными умолчаниями.
  • templates/ содержит файлы манифестов с пропусками. Всё, что лежит в этом каталоге и не начинается с _, Helm считает манифестом и отправляет в кластер. Исключение: NOTES.txt (он есть в дереве, которое создаёт helm create). Это не манифест, а текст-подсказка, Helm печатает его после установки; увидеть его можно через helm install --dry-run=client.
  • Файл, имя которого начинается с подчёркивания (_helpers.tpl), манифестом не является. В нём хранятся именованные «кусочки», их подключают в других шаблонах (подробнее в разделе про include).
  • values-dev.yaml не читается автоматически. Его нужно явно передать флагом -f.

Как из этого получается манифест, ты увидишь в следующих разделах.

Так выглядит Chart.yaml нашего чарта, поле за полем:

apiVersion: v2                                 # формат чарта (v2 у Helm 3 и 4)
name: notes                                    # имя чарта; по нему релиз называют по умолчанию
description: Приложение Заметки (без БД, Gateway и секретов)   # для людей
type: application                              # application ставится в кластер, library только даёт шаблоны другим чартам
version: 0.1.0                                 # версия шаблонов; растёт, когда меняешь чарт
appVersion: "0.4.1"                            # версия приложения; у нас это тег образа notes:0.4.1

appVersion взят в кавычки специально. Без них YAML прочитает 0.4.1 как строку сам, но 1.10 превратился бы в число 1.1, и версия исказилась бы. Кавычки для версий стоит писать всегда.

Осторожно, путаница: каталог templates/ не «шаблоны Jinja» и не обычные манифесты: это файлы на языке Go-шаблонов (разбираем ниже), поэтому их нельзя применять через kubectl apply -f напрямую. Если применить, kubectl увидит {{ и вернёт ошибку разбора YAML.

Прикинь сам: ты положил в templates/ файл notes.tpl с Deployment. Попадёт ли он в кластер? А если назвать его _notes.yaml?

notes.tpl попадёт: манифестом считается любой файл без подчёркивания в начале имени, а расширение не важно. _notes.yaml манифестом не станет, это хранилище «кусочков».

Главное: в чарте обязателен Chart.yaml; values.yaml есть почти всегда, но Helm его не требует. В кластер уходит всё из templates/, что не начинается с _ (кроме NOTES.txt).

Теперь посмотрим, как значения из values.yaml складываются в итог.

Values: значения и их приоритет

Чтобы одни и те же шаблоны давали разные результаты, нужен слой значений, отдельный от шаблонов. Тогда отличие dev от prod это два маленьких файла, а не две копии всего приложения.

Правило одно: чем ближе значение к моменту запуска команды, тем оно сильнее. Умолчания слабее всего, а разовый --set побеждает всё.

Helm собирает итоговый набор значений в три слоя, каждый следующий перекрывает предыдущий:

flowchart TD
    A["1. values.yaml чарта<br>самые слабые: умолчания"] -->|"перекрываются"| B["2. файлы из -f (по порядку)<br>-f values-dev.yaml -f values-local.yaml"]
    B -->|"перекрываются"| C["3. --set ключ=значение<br>самые сильные: разовые правки в командной строке"]

Вложенные значения складываются по ключам, а не заменяются целиком. Если в values.yaml есть config.LOG_LEVEL: info и config.PORT: "8080", а в файле values-dev.yaml только config.LOG_LEVEL: debug, то PORT останется, а поменяется один LOG_LEVEL. Списки (массивы) наоборот заменяются целиком.

Возьмём значения нашего чарта и посчитаем итог для команды:

helm template notes helm/notes -f helm/notes/values-dev.yaml --set replicaCount=5
Ключ values.yaml values-dev.yaml –set Итог
replicaCount 3 2 5 5 (побеждает --set)
config.LOG_LEVEL info debug нет debug (побеждает файл)
config.PORT “8080” нет нет “8080” (осталось умолчание)
gateway.host notes.lab нет нет notes.lab

Из четырёх ключей три взяты из разных слоёв, и это нормально: слои не заменяют друг друга целиком.

Прикинь сам: в values.yaml replicaCount: 3, в values-dev.yaml 2, а в командной строке --set replicaCount=5. Сколько реплик получишь?

Пять: --set сильнее файлов, а файл -f сильнее умолчаний. Без -f файл values-dev.yaml вообще не читается.

Осторожно: --set разбирает запись сам, поэтому --set config.PORT=8080 даст число, а не строку, а для переменной окружения это важно (ниже разберём quote). Кроме того, через месяц никто не вспомнит, с каким --set ставили релиз: постоянные отличия записывай в файл значений и клади в git.

Проверь понимание: в values.yaml стоит replicaCount: 3, в values-dev.yaml replicaCount: 2. Ты запускаешь helm template notes helm/notes без -f. Сколько реплик получишь?

Ответ

Три. Файл values-dev.yaml сам не подключается, его нужно указать флагом -f. Без флага работают только значения по умолчанию из values.yaml.

Главное: слои значений от слабого к сильному: values.yaml, файлы -f по порядку, --set; вложенные ключи складываются, списки заменяются целиком.

Значения лежат отдельно, а подставляет их шаблон.

Шаблон: как подставляются значения

Нужен способ сказать в YAML «здесь будет значение, которое возьмём из values». Для этого Helm использует язык шаблонов Go (Go templates): всё, что внутри двойных фигурных скобок {{ ... }}, Helm вычисляет, остальной текст оставляет как есть.

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

Внутри {{ }} доступны три главные «папки» с данными, они начинаются с точки:

.Values     значения из values.yaml, -f и --set      .Values.replicaCount
.Release    данные об установке                      .Release.Name  (имя релиза)
                                                     .Release.Namespace
                                                     .Release.Service  (всегда "Helm")
.Chart      данные из Chart.yaml                     .Chart.Name  .Chart.Version  .Chart.AppVersion

Точка в начале обозначает «текущий контекст», то есть корневой объект со всеми этими папками. Путь читается слева направо, как путь к файлу: .Values.gateway.host это «в папке Values возьми gateway, в ней host».

Символ | (вертикальная черта, пайп) знаком тебе по bash: передаёт результат слева в функцию справа. Здесь так же: {{ .Values.gateway.host | quote }} берёт значение и пропускает его через функцию quote, которая оборачивает его в кавычки.

Из нашего deployment.yaml:

spec:
  replicas: {{ .Values.replicaCount }}

Разбор: Helm видит {{ .Values.replicaCount }}, идёт в значения, находит replicaCount. При -f values-dev.yaml это 2. Получается строка replicas: 2. А вот строка с образом:

image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
  • .Values.image.repository даёт ghcr.io/CHANGE_ME/notes;
  • .Values.image.tag пуст (""), поэтому функция default берёт запасное значение .Chart.AppVersion, то есть 0.4.1;
  • итог: image: "ghcr.io/CHANGE_ME/notes:0.4.1".

Именно это ты увидишь в выводе helm template в задании 2.

Прикинь сам: в values.yaml image.tag: "". Какой тег получит образ и откуда он взят?

Тег 0.4.1 из .Chart.AppVersion: пустая строка считается «нет значения», и default берёт запасное.

Осторожно: не думай, что пропуск {{ }} можно поставить где угодно. Подставляется текст, поэтому после подстановки YAML обязан оставаться правильным. Слова вроде yes и on без кавычек некоторые разборщики YAML читают как булево значение, а 8080 без кавычек станет числом. Для переменных окружения и меток строки лучше пропускать через quote.

Главное: внутри {{ }} доступны .Values, .Release и .Chart; пайп | передаёт результат в функцию вроде default или quote.

Одной подстановки мало, шаблоны умеют условия, циклы и функции.

Конструкции шаблонов: условия, циклы, функции

Одной подстановки мало. Иногда объект нужен не всегда (HTTPRoute только если задан хост), иногда список надо перебрать (все переменные из config), иногда значение нужно обязательно.

Эти инструкции Helm выполняет молча: если записал неверно, ошибки может не быть, а результат окажется не тем. Поэтому итог всегда смотри через helm template.

Конструкции нашего чарта по одной:

# 1. Подстановка значения
replicas: {{ .Values.replicaCount }}

# 2. Значение по умолчанию: берётся правая часть, если левая пуста
image: {{ .Values.image.tag | default .Chart.AppVersion }}

# 3. Обязательное значение: если пусто, рендер останавливается с сообщением
- {{ required "нужен gateway.host" .Values.gateway.host | quote }}

# 4. Цикл по словарю: для каждой пары ключ-значение печатаем строку
{{- range $k, $v := .Values.config }}
{{ $k }}: {{ $v | quote }}
{{- end }}

# 5. Условие (в нашем чарте не нужно, приводим для примера)
{{- if .Values.gateway.host }}
# ... блок печатается, только если host задан
{{- end }}

# 6. Вставка целой структуры как YAML с нужным отступом
resources:
  {{- toYaml .Values.resources | nindent 12 }}

Разбор непонятного:

  • $k и $v это переменные цикла. Знак доллара нужен, чтобы отличить их от путей с точкой. Пара $k, $v := .Values.config читается так: «для каждой пары в .Values.config кладу ключ в $k, значение в $v».
  • {{- ... }} с дефисом слева убирает пробелы и перевод строки перед скобками. Справа так же работает -}}. Без дефиса в результате остаются пустые строки: для YAML они безвредны, но рядом с nindent путают глаз.
  • toYaml превращает структуру из values (словарь requests, limits) обратно в текст YAML.
  • nindent 12 это «new line + indent»: сначала добавляет перевод строки, затем сдвигает каждую строку на 12 пробелов. Число подбирают так: столько пробелов, на каком уровне вложенности должен стоять вставляемый блок.

В deployment.yaml блок resources стоит так:

spec:                       уровень 0
  template:                 2 пробела
    spec:                   4
      containers:           6
        - name: notes       8  (это элемент списка)
          resources:        10 (поле контейнера)
            requests:       12 <-- сюда должны встать ключи из toYaml

Поле resources: стоит на 10 пробелах. Его содержимое (requests, limits) должно быть глубже на 2, то есть на 12. Поэтому nindent 12. Итог после вставки:

          resources:
            limits:
              cpu: 200m
              memory: 128Mi
            requests:
              cpu: 50m
              memory: 64Mi

Обрати внимание: ключи вывелись по алфавиту (limits раньше requests), потому что toYaml сортирует ключи. Порядок в YAML ничего не меняет.

Осторожно, путаница: неверное число в nindent самая частая поломка шаблонов. Что важно: результат может остаться формально верным YAML, но с неправильным смыслом. При nindent 10 вместо 12 helm template молча отработает, а kubeconform в задании 5 пожалуется на additional properties 'limits', 'requests' not allowed: ключи requests и limits оказались на уровне контейнера. Поэтому в связке нужны обе проверки: helm template и валидатор схемы.

Прикинь сам: в values.yaml нет gateway.host. Что сделает required "нужен gateway.host" .Values.gateway.host и чем это лучше default?

required остановит рендер с сообщением ещё до обращения к кластеру. default молча подставил бы выдуманное значение, и приложение уехало бы с чужим хостом.

Главное: default задаёт запасное значение, required останавливает рендер, range перебирает, toYaml с nindent вставляет блок на нужной глубине.

Повторяющиеся куски удобно записать один раз, и для этого есть хелперы.

Хелперы: define и include

Набор меток (app.kubernetes.io/name, instance, version) нужен в каждом объекте. Если копировать его в пять файлов, получим ту же проблему копий, но уже внутри чарта. Поэтому повторяющийся кусок записывают один раз и вызывают по имени.

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

В файле _helpers.tpl кусок объявляется через define "имя", а в шаблонах подключается через include "имя" контекст. Второй аргумент (контекст) обычно точка .: это значит «передай корневые данные, чтобы внутри работали .Release и .Chart».

Разобранный пример.

{{- define "notes.labels" -}}
app.kubernetes.io/name: notes
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
{{- end }}

Здесь printf "%s-%s" .Chart.Name .Chart.Version склеивает имя и версию в notes-0.1.0. Вызов: {{- include "notes.labels" . | nindent 4 }}. Он вставляет пять строк меток и сдвигает их на 4 пробела. После рендера в метаданных Deployment получится:

  labels:
    app.kubernetes.io/name: notes
    app.kubernetes.io/instance: notes
    app.kubernetes.io/version: "0.4.1"
    app.kubernetes.io/managed-by: Helm
    helm.sh/chart: notes-0.1.0

В чарте два хелпера: notes.labels (полный набор меток для метаданных) и notes.selectorLabels (одна метка app.kubernetes.io/name: notes). Зачем два, мы разберём в задании 2.

Осторожно, путаница: include и template (старая команда). Используй include: только его результат можно передать дальше по пайпу в nindent. Второе: имена хелперов общие для всего чарта и всех его зависимостей, поэтому начинай имя с названия чарта (notes.labels), иначе можно случайно перекрыть чужой хелпер.

Главное: define объявляет кусок в _helpers.tpl, include вызывает его и передаёт контекст (точка ., без неё внутри хелпера не будет .Release и .Chart); имя начинай с названия чарта.

Теперь поймём, как Helm хранит историю установок.

Релиз, ревизия и история

kubectl apply применяет файл и забывает. Чтобы вернуться на вчерашнюю версию, пришлось бы найти вчерашний файл в git и применить его. Helm запоминает каждую установку, поэтому «вернись на две версии назад» это одна команда.

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

Установленный экземпляр чарта называется релиз (release), у него есть имя (у нас notes) и живёт он в конкретном namespace. Один чарт можно поставить много раз под разными именами: notes-dev и notes-prod это два независимых релиза. Каждая установка или обновление создаёт ревизию (revision) с порядковым номером 1, 2, 3.

Состояние хранится в кластере, в Secret (объект для чувствительных данных, урок 5.6) с типом helm.sh/release.v1. По одному на ревизию, с именами вида sh.helm.release.v1.notes.v1, ...v2. Внутри упакованы: чарт, значения, итоговый манифест и статус.

Жизненный цикл ревизии:

helm upgrade --install (1-й раз)     ревизия 1  deployed
helm upgrade (новые значения)        ревизия 1  superseded   ревизия 2  deployed
helm upgrade (плохой образ)          ревизия 2  superseded   ревизия 3  deployed (или failed)
helm rollback notes 2                ревизия 3  superseded   ревизия 4  deployed  "Rollback to 2"

Статусы: deployed (текущая), superseded (заменена более новой), failed (не удалась), pending-install и pending-upgrade (операция идёт или оборвалась).

Ты на ревизии 3 (плохой образ). Команда helm rollback notes 2 берёт манифест из ревизии 2, применяет его и записывает как ревизию 4 с описанием Rollback to 2. Номер 3 остаётся в истории, счётчик не откатывается назад. Такая история честно показывает, что происходило, включая неудачный выпуск.

Помнишь «историю установок» из начала урока? Вот как она выглядит у настоящего релиза: helm list показывает установленные релизы, helm history их ревизии.

$ helm list -n notes
NAME    NAMESPACE   REVISION   STATUS     CHART        APP VERSION
notes   notes       3          deployed   notes-0.2.0  0.4.1

$ helm history notes -n notes
REVISION   STATUS       CHART        DESCRIPTION
1          superseded   notes-0.1.0  Install complete
2          superseded   notes-0.1.0  Upgrade complete
3          deployed     notes-0.2.0  Upgrade complete

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

Осторожно, путаница: откат возвращает только то, что описано в манифестах. Данные в базе, применённые миграции схемы, файлы на дисках он не откатывает. Если ревизия 3 успела изменить структуру таблиц, откат образа приложения не вернёт таблицы.

Прикинь сам: ты на ревизии 3 с плохим образом и сделал helm rollback notes 2. Какой номер у текущей ревизии?

Четвёртый: откат создаёт новую запись с содержимым ревизии 2. Ревизия 3 остаётся в истории.

Проверь понимание: где Helm хранит историю релизов и что случится, если удалить эти Secret?

Ответ

В Secret типа helm.sh/release.v1 в namespace релиза, по одному на ревизию. Если их удалить, поды и Service продолжат работать, но Helm забудет о релизе: helm list его не покажет, откатиться будет нельзя, а повторный install упрётся в уже существующие объекты.

Главное: релиз это установленный чарт под именем, ревизия это номер версии; история лежит в Secret helm.sh/release.v1, а откат не возвращает данные в базе.

Остаётся разобрать команды, от безопасных к опасным.

Команды Helm: от безопасных к опасным

Между «написал шаблон» и «изменил кластер» должны быть шаги проверки, каждый следующий рискованнее предыдущего. Порядок ниже это порядок увеличения риска.

Как устроено.

Команда Что делает Кластер нужен Риск
helm lint Проверяет чарт статически: синтаксис, обязательные поля нет нулевой
helm template Рендерит шаблоны и печатает готовый YAML нет нулевой
helm install Ставит новый релиз да меняет кластер
helm upgrade --install Ставит, если релиза нет; обновляет, если есть да меняет кластер
helm history Показывает ревизии да нулевой
helm get values / manifest Показывает значения и манифест установленного релиза да нулевой
helm rollback Возвращает состояние прошлой ревизии да меняет кластер
helm uninstall Удаляет все объекты релиза да опасно

Форма upgrade --install идемпотентна (повторный запуск даёт тот же результат, а не ошибку «уже есть»), поэтому её пишут в CI-скриптах: одна команда работает и на первой установке, и на сотой.

Полезные флаги установки и обновления:

  • -n notes (--namespace): в какой namespace ставить и где искать релиз;
  • -f файл: файл значений; можно указать несколько, применяются по порядку;
  • --set ключ=значение: разовое значение;
  • --wait: дождаться готовности ресурсов (для Deployment это значит, что нужные поды стали Ready) и только тогда вернуть управление;
  • --timeout 3m: сколько ждать, по умолчанию 5 минут;
  • --rollback-on-failure: если обновление не удалось, автоматически откатить на прошлую рабочую ревизию. Включает ожидание --wait. В Helm 3 и в старых статьях этот флаг называется --atomic; в Helm 4 старое имя ещё принимается, но печатает предупреждение об устаревании.

helm template notes helm/notes -n notes самая полезная команда отладки. Ты видишь, что уедет в кластер, ничего не меняя. Вывод начинается с комментария # Source: notes/templates/configmap.yaml, он подсказывает, из какого шаблона взят блок. Блоки разделены строкой ---. Если YAML сломан, добавь флаг --debug: он напечатает результат рендера даже неправильный, и по номеру строки в ошибке ты найдёшь место.

Осторожно, путаница: helm lint не запускает шаблоны на реальных значениях и не сверяет их со схемой Kubernetes. Он пропустит неверную apiVersion или лишнее поле. Поэтому схему проверяет отдельная утилита kubeconform, которую ты будешь запускать над выводом helm template.

Главное: порядок рисков такой: lint и template ничего не меняют, install, upgrade и rollback меняют кластер, uninstall опасен. В CI пишут upgrade --install: обычный install при существующем релизе падает с cannot reuse a name that is still in use.

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

Хуки

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

Хук (hook) это обычный манифест (чаще всего Job из урока 5.8) с аннотацией helm.sh/hook. В аннотации пишут момент запуска: pre-install, pre-upgrade, post-install, post-upgrade и другие. Helm запускает такой объект в нужный момент и ждёт его завершения. Упавший pre-upgrade хук останавливает обновление, и новые поды не появляются.

В нашем чарте хуков нет, мы упоминаем их, чтобы ты узнал их в чужих чартах. Объекты-хуки не входят в состав релиза как обычные: helm uninstall их не удаляет. Чтобы убирать их после выполнения, задают helm.sh/hook-delete-policy (hook-succeeded или hook-failed) или TTL для Job.

Главное: хук это обычный манифест (чаще Job) с аннотацией helm.sh/hook; упавший pre-upgrade останавливает обновление, а uninstall хук не удаляет без hook-delete-policy.

Чарт и приложение развиваются с разной скоростью, и у них разные версии.

Версия чарта и версия приложения

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

В Chart.yaml два номера. version это версия самого чарта (шаблонов), она растёт, когда меняешь шаблоны. appVersion это версия упакованного приложения, у нас это тег образа 0.4.1. Их путают, а зря: можно выпустить чарт 0.1.1 с тем же приложением 0.4.1, и наоборот.

Чарты нужно где-то хранить, чтобы ими делились. Реестр (registry) это склад с адресом: ты кладёшь туда упакованный чарт и скачиваешь его другой командой или на другой машине. Без склада чарты пришлось бы пересылать файлами. Чарты можно хранить в OCI-реестрах (адреса вида oci://ghcr.io/..., тех же, где хранятся Docker-образы): это поддерживается с Helm 3.8 и в Helm 4 тоже, а классические репозитории с файлом index.yaml (как podinfo в задании 6) по-прежнему работают. Ещё две вещи отличают v4 от v3: для новых релизов по умолчанию server-side apply (сервер сам разбирается с конфликтами полей, настройка --server-side=auto) и плагины на WebAssembly. Для этого урока разница не важна, команды те же, кроме имени флага --rollback-on-failure.

Главное: version это версия шаблонов чарта (поправил пробу в шаблоне: растёт она), appVersion это версия приложения (вышел новый образ: растёт она); чарты хранят в реестрах, в том числе OCI.

Перед установкой стоит посмотреть, что именно уедет в кластер.

Рендер и проверка до установки

Ошибка в шаблоне опасна тем, что видна только после отправки в кластер: отступ съехал, значение не подставилось, и Deployment не создаётся. Хочется увидеть готовый YAML заранее и ничего не сломать.

Для этого Helm умеет рендерить шаблоны локально, не обращаясь к кластеру. Оговорка: такой рендер не знает, примет ли кластер получившийся YAML. Он проверяет только шаблон, а не то, что скажет API-сервер.

Две команды, которые ничего не меняют в кластере. helm lint проверяет чарт: синтаксис, обязательные файлы, явные ошибки. helm template делает рендер и печатает итоговый YAML в терминал. В вывод попадают только объекты из templates/, подставленные значения видны прямо в строках.

Ты поменял replicaCount на 3 в values.yaml. Запускаешь helm template и ищешь replicas: в Deployment. Видишь replicas: 3: значение подставилось. Видишь replicas: 2: значение берётся откуда-то ещё, например, из --set или файла -f с более высоким приоритетом (порядок разбирали выше).

Если helm template напечатал правильный YAML, а установка упала с ошибкой API-сервера, шаблон в порядке: ошибку выдал кластер (неверное поле, нет типа ресурса или объект принадлежит другому владельцу). Читай текст ошибки.

Главное: порядок такой: lint, template, потом upgrade --install; lint и template не ходят в кластер, поэтому схему проверяют отдельно kubeconform.

Теперь посмотрим, что делает helm upgrade внутри.

Что происходит внутри helm upgrade

Без понимания порядка шагов непонятно, почему Helm иногда «молчит» и ничего не меняет, а иногда ругается на чужие объекты. Порядок короткий, его полезно держать в голове.

Кто считает разницу между старым и новым состоянием, зависит от версии Helm. В Helm 3 патч считает сам Helm (трёхстороннее слияние: старый манифест, новый манифест и живой объект в кластере). В Helm 4 для новых релизов по умолчанию работает server-side apply: Helm отдаёт манифест целиком, а что менять, решает API-сервер. Режим выбирает флаг --server-side=auto и запоминает его в релизе, поэтому релиз, поставленный в Helm 3, продолжает обновляться по-старому. Дальше шаги описаны так, чтобы подходить обеим версиям.

Команда проходит шаги по порядку:

  1. Helm читает чарт и значения (values.yaml, -f, --set) и делает рендер в итоговый YAML.
  2. Достаёт из кластера манифест текущей ревизии (из Secret sh.helm.release...) и сравнивает с новым.
  3. Применяет в кластер объекты нового манифеста (в Helm 3 по патчу, который посчитал сам Helm, в Helm 4 для новых релизов через server-side apply). Меняются только отличающиеся поля, а объекты, которые исчезли из манифеста, удаляются.
  4. Записывает новую ревизию в новый Secret, а предыдущей ставит статус superseded.
  5. Если указан --wait (или --rollback-on-failure), ждёт, пока поды станут готовы, и только потом возвращает управление.

Ты поменял в values.yaml тег образа с 0.4.1 на 0.4.2 и запустил helm upgrade. Рендер даст Deployment с новым образом, а Service, ConfigMap и HTTPRoute не изменились. Helm применит все объекты, но отличие найдётся только в Deployment: Kubernetes начнёт rolling update, а в истории появится ревизия 2. У Service, ConfigMap и HTTPRoute ничего не изменится.

Прикинь сам: ты запустил helm upgrade с теми же значениями, что в текущей ревизии. Что произойдёт с подами?

Ничего: манифест не изменился, Kubernetes поды не перезапустит. В истории появится новая ревизия с той же конфигурацией. Чтобы поды перезапускались при смене ConfigMap, в шаблон кладут контрольную сумму файла как аннотацию пода, тогда манифест Deployment меняется сам (приём из практики).

Главное: Helm применяет все объекты нового манифеста (в Helm 3 патч считает сам Helm, в Helm 4 для новых релизов это server-side apply), а менять приходится только разницу; ревизия растёт, даже если разницы нет.

Остаётся решить, что вообще класть в чарт.

Чего в чарт не кладём

Соблазн упаковать в чарт всё подряд. Но у разных объектов разный срок жизни, и их нельзя удалять и обновлять вместе.

Чарт содержит только приложение: Deployment, Service, ConfigMap, HTTPRoute. Остальное остаётся платформой и лежит в k8s/base/:

  • Namespace (00-namespace.yaml): он существует до релиза и после него;
  • Gateway (30-envoyproxy.yaml, 31-gateway.yaml): общий для нескольких сервисов;
  • PostgreSQL (40-postgres.yaml): база живёт годами, приложение выпускается ежедневно;
  • CronJob бэкапа (60-pg-backup-cronjob.yaml).

Разбери это на вопросе: «что случится при helm uninstall notes?» Если в чарте лежит Postgres, helm uninstall удалит StatefulSet и Pod базы, то есть будет простой. Дальше с данными два случая:

  • PVC, которые StatefulSet создал сам по volumeClaimTemplates (урок 5.5), в манифесте релиза не записаны, поэтому helm uninstall их не трогает и данные остаются.
  • PVC, записанный в templates/ как отдельный объект, входит в релиз. helm uninstall удалит его, а вместе с ним и данные, если у StorageClass стоит reclaimPolicy: Delete. Проверь kubectl -n notes get pvc до и после uninstall: во втором случае claim пропадёт.

Защита от второго случая: аннотация helm.sh/resource-policy: keep на PVC (и на Secret): Helm при uninstall оставит такой объект. Но чище вынести базу из чарта вообще. Поэтому объекты с чужим и более долгим жизненным циклом в релиз не входят.

В проде базой часто занимается оператор (operator): программа в кластере, которая сама создаёт реплики БД, делает бэкапы и чинит сбои, как дежурный админ, который не спит. Его ставят отдельно от чарта приложения (подробно в уроке 9.2).

Секреты вне чарта. Пароль, записанный в values.yaml, попадёт в git, в вывод helm get values и в Secret релиза. Чарт вместо этого ссылается на готовый Secret по имени (existingSecret: notes-db), а сам Secret создаётся отдельно командой (как в уроке 5.6; правильный способ хранить секреты разберём в уроке 9.2).

Прикинь сам: почему helm uninstall notes не удалит PostgreSQL?

Helm удаляет только объекты, записанные в манифест релиза. Postgres ставится отдельно из k8s/base/ и в релиз не входит.

Осторожно: не думай, что helm install можно применить поверх объектов, уже созданных через kubectl apply. Helm откажет: invalid ownership metadata. Он не берёт под контроль чужие объекты без своих меток владельца (app.kubernetes.io/managed-by: Helm, meta.helm.sh/release-name). Есть два пути: удалить старые и поставить релиз (наш выбор, кластер учебный) или дописать метки и аннотации вручную («усыновить»), если простой недопустим.

Главное: в чарт кладут только приложение; Namespace, Gateway, базу и секреты держат вне релиза, а пароли в values.yaml не пишут.

Это основа. Остальное, что часто встречается в чужих чартах и на собеседованиях, собрано ниже.

Что ещё встретишь на работе

В «Заметках» нам это не понадобилось, но в первый месяц на настоящем проекте ты встретишь каждый пункт.

  • helm diff upgrade. Это плагин helm-diff (ставится командой helm plugin install https://github.com/databus23/helm-diff; Helm 4 по умолчанию проверяет подпись плагина, и для плагина без подписи нужен флаг --verify=false, так что ставь только то, чему доверяет твоя команда). Он показывает построчную разницу между релизом в кластере и тем, что будет после обновления. Это kubectl diff для релиза: смотришь, что изменится, и только потом запускаешь upgrade.
  • --dry-run=server. Флаг install и upgrade (Helm с 3.13): Helm рендерит шаблоны и отправляет результат API-серверу, тот проверяет его как настоящий, но ничего не сохраняет. Ловит ошибки, которых не видно у helm template: неизвестное поле, отсутствующий тип объекта.
  • Зависимости (subcharts). Чарт может зависеть от других чартов: в Chart.yaml записывают блок dependencies (имя, версия, репозиторий). Команда helm dependency update скачивает их в каталог charts/ и записывает точные версии в Chart.lock, чтобы у всей команды сборка была одинаковой. Значения чужого чарта-зависимости задают в values.yaml под ключом с его именем.
  • values.schema.json. Файл рядом с values.yaml, в котором на языке JSON Schema (формат описания «что должно лежать в JSON») записано, какие ключи бывают и каких они типов. Helm проверяет значения по нему при lint, template, install и upgrade: опечатка в replicaCount или строка там, где ждут число, ловится до кластера.
  • Каталог crds/. Если чарту нужны CRD (расширения Kubernetes, как у Gateway API), их кладут в crds/. Helm ставит их только при первой установке, при upgrade не обновляет и при uninstall не удаляет, поэтому новую версию CRD применяют руками через kubectl apply. Из-за этого установка чартов, которые приносят свои CRD, иногда ломается на ровном месте.
  • --reuse-values и --reset-then-reuse-values. По умолчанию upgrade берёт значения из нового чарта плюс то, что ты передал сейчас. --reuse-values берёт значения прошлой ревизии и игнорирует новые умолчания чарта: если в свежей версии чарта появился ключ, он не придёт. Вариант --reset-then-reuse-values сначала берёт умолчания нового чарта, потом накладывает твои прошлые значения и только потом -f и --set этого запуска. Безопаснее всего хранить значения в файле и каждый раз передавать -f.
  • --history-max. Сколько ревизий хранить (по умолчанию 10): старые Secret релиза удаляются, чтобы не копились.
  • helm test. Запускает поды из шаблонов с аннотацией helm.sh/hook: test, например проверку, что сервис отвечает. Если все такие поды завершились успешно, тест пройден.
  • --take-ownership. Флаг install и upgrade в Helm 4.3.0 (сверен по helm upgrade --help): Helm берёт под управление объекты, созданные не им, пропуская проверку аннотаций. А --force-replace (в Helm 3 назывался --force) заставляет пересоздавать объекты вместо обновления, так что используй его осознанно.

Главное: на собеседовании чаще всего спрашивают helm diff, values.schema.json, crds/ (Helm не обновляет CRD при upgrade) и --reuse-values.

Теперь пора собрать чарт «Заметок» руками.

Практика

Кластер kind-notes из урока 5.1 запущен, в namespace notes работают Postgres, Envoy Gateway, Secret notes-db и Secret notes-tls, приложение развёрнуто манифестами 10-deployment.yaml, 20-service.yaml, 32-httproute.yaml, 50-configmap.yaml из k8s/base/. Все команды выполняются в ~/notes.

Блоки «Что должно получиться» помечены как примерные там, где вывод кластера зависит от времени и хешей: сверяй смысл, а не побуквенно. Хеши подов, даты и номера ревизий у тебя будут свои.

Задание 1. Установка Helm и первый чарт

Цель: поставить Helm с проверкой контрольной суммы и увидеть, что генерирует helm create.

Предскажи: что покажет sha256sum -c, если архив скачался обрезанным?

Ответ

FAILED и код возврата 1: сумма не совпадёт. Ставить такой файл нельзя.

Разбор команд перед запуском:

  • curl -fsSLO URL скачивает файл (флаги: -f падать при ошибке HTTP, -s тихо, -S но показывать ошибки, -L идти по перенаправлениям, -O сохранить под именем из URL). Так же ты скачивал файлы в уроке 1.6.
  • sha256sum -c файл читает из файла строку «контрольная сумма и имя», считает сумму у настоящего файла и сравнивает. Контрольная сумма (checksum) это «отпечаток» файла: если изменился хоть один байт, отпечаток другой. Так мы убеждаемся, что архив скачан целиком и не подменён.
  • tar -xzf распаковывает архив (x извлечь, z он сжат gzip, f файл).
  • sudo install linux-amd64/helm /usr/local/bin/helm копирует программу в каталог, где система ищет команды, и ставит право на запуск.

Шаги:

  1. Скачай релиз Helm v4.3.0 и проверь SHA256 (для ARM замени amd64 на arm64):

    cd /tmp
    curl -fsSLO https://get.helm.sh/helm-v4.3.0-linux-amd64.tar.gz
    curl -fsSLO https://get.helm.sh/helm-v4.3.0-linux-amd64.tar.gz.sha256sum
    sha256sum -c helm-v4.3.0-linux-amd64.tar.gz.sha256sum
    tar -xzf helm-v4.3.0-linux-amd64.tar.gz
    sudo install linux-amd64/helm /usr/local/bin/helm
    helm version --short
    cd ~/notes
    

    Последняя строка возвращает тебя в репозиторий: дальше все пути (helm/notes/...) считаются от ~/notes.

  2. Посмотри, что генерирует helm create. Команда создаёт заготовку чарта (helm create имя), find ... | sort печатает все файлы каталога по алфавиту:

    helm create /tmp/demo
    find /tmp/demo -type f | sort
    rm -rf /tmp/demo
    

Что должно получиться:

helm-v4.3.0-linux-amd64.tar.gz: OK
v4.3.0+gbec5b06
/tmp/demo/.helmignore
/tmp/demo/Chart.yaml
/tmp/demo/templates/NOTES.txt
/tmp/demo/templates/_helpers.tpl
/tmp/demo/templates/deployment.yaml
/tmp/demo/templates/hpa.yaml
/tmp/demo/templates/httproute.yaml
/tmp/demo/templates/ingress.yaml
/tmp/demo/templates/service.yaml
/tmp/demo/templates/serviceaccount.yaml
/tmp/demo/templates/tests/test-connection.yaml
/tmp/demo/values.yaml

Как читать вывод: OK после имени архива значит, что отпечаток совпал. Строка v4.3.0+gbec5b06 это версия Helm, а часть после + хеш сборки. Полный helm version без --short печатает структуру version.BuildInfo{...}. Если ты на ARM (Mac на Apple Silicon с Linux в ВМ), качай arm64.

Объясни себе:

  • Зачем сверять контрольную сумму, а не запускать curl | bash?
  • helm create даёт десяток файлов (hpa.yaml, ingress.yaml, serviceaccount.yaml), которые «Заметкам» не нужны. Мы соберём небольшой чарт по образцу: важно понимать назначение файлов и как значения превращаются в поля манифеста. Чем helm create полезен новичку, а чем вреден (подсказка: десяток лишних шаблонов)?

Типичные ошибки:

  • sha256sum: WARNING: 1 computed checksum did NOT match: файл скачан не полностью или подменён. Скачай заново, не устанавливай.

Задание 2. Чарт «Заметок»: Chart.yaml, values и шаблоны

Цель: описать приложение как чарт и убедиться, что helm template даёт то же, что лежало в k8s/base/.

Измени по образцу. Файлы ниже можно переносить из урока. Сейчас нужно понимать, где задаются образ, число реплик и порт, откуда шаблон берёт эти значения и что получается после helm template. Писать весь чарт по памяти не нужно.

Проверяй себя по этапам. Сначала создай файлы и выполни проверку из шага 9. Затем измени число реплик в values-dev.yaml и найди изменение в полученном Deployment: файл из -f перекрывает значения из основного values.yaml. Предскажи результат до запуска.

Небольшую правку шаблона сделай сам: добавь свою аннотацию в metadata.annotations Deployment. Проверь её полным рендером helm template notes helm/notes -n notes -f helm/notes/values-dev.yaml, без фильтра grep из шага 9: фильтр скрывает аннотации.

Предскажи: что произойдёт с релизом, если ты не задашь image.tag, и что хочется от чарта в этом случае?

Ответ

Разумное поведение: взять appVersion из Chart.yaml (0.4.1). Так тег образа по умолчанию совпадает с версией приложения, а latest не появляется нигде.

Шаги:

  1. Создай helm/notes/Chart.yaml:

    apiVersion: v2
    name: notes
    description: Приложение Заметки (без БД, Gateway и секретов)
    type: application
    version: 0.1.0
    appVersion: "0.4.1"
    
  2. Создай helm/notes/values.yaml. Пользователя GitHub подставь свой вместо CHANGE_ME:

    replicaCount: 3
    
    image:
      repository: ghcr.io/CHANGE_ME/notes
      tag: ""            # пусто: берётся appVersion из Chart.yaml
      pullPolicy: IfNotPresent
    
    # Готовый Secret с ключом DATABASE_URL, создан вне чарта
    existingSecret: notes-db
    
    config:
      STORE: postgres
      HOST: "0.0.0.0"
      PORT: "8080"
      LOG_LEVEL: info
      APP_VERSION: "0.4.1"
    
    resources:
      requests:
        cpu: 50m
        memory: 64Mi
      limits:
        cpu: 200m
        memory: 128Mi
    
    gateway:
      name: notes-gw
      host: notes.lab
    
  3. Создай helm/notes/values-dev.yaml:

    replicaCount: 2
    config:
      LOG_LEVEL: debug
    
  4. Создай helm/notes/templates/_helpers.tpl:

    {{- define "notes.labels" -}}
    app.kubernetes.io/name: notes
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
    {{- end }}
    
    {{- define "notes.selectorLabels" -}}
    app.kubernetes.io/name: notes
    {{- end }}
    
  5. Создай helm/notes/templates/configmap.yaml:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: {{ .Release.Name }}-config
      labels:
        {{- include "notes.labels" . | nindent 4 }}
    data:
      {{- range $k, $v := .Values.config }}
      {{ $k }}: {{ $v | quote }}
      {{- end }}
    
  6. Создай helm/notes/templates/deployment.yaml. Селектор оставляем как в уроке 5.3 (app.kubernetes.io/name: notes), иначе Service перестанет находить Pod’ы:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: {{ .Release.Name }}
      labels:
        {{- include "notes.labels" . | nindent 4 }}
    spec:
      replicas: {{ .Values.replicaCount }}
      strategy:
        type: RollingUpdate
        rollingUpdate:
          maxSurge: 1
          maxUnavailable: 0
      selector:
        matchLabels:
          {{- include "notes.selectorLabels" . | nindent 6 }}
      template:
        metadata:
          labels:
            {{- include "notes.labels" . | nindent 8 }}
          annotations:
            # при смене конфига меняется хеш, и Pod'ы перезапускаются
            checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
        spec:
          containers:
            - name: notes
              image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
              imagePullPolicy: {{ .Values.image.pullPolicy }}
              ports:
                - name: http
                  containerPort: 8080
              envFrom:
                - configMapRef:
                    name: {{ .Release.Name }}-config
              # из Secret только один ключ, как в уроке 5.6
              env:
                - name: DATABASE_URL
                  valueFrom:
                    secretKeyRef:
                      name: {{ required "нужен existingSecret" .Values.existingSecret }}
                      key: DATABASE_URL
              startupProbe: { httpGet: { path: /healthz, port: http }, periodSeconds: 2, failureThreshold: 30 }
              livenessProbe: { httpGet: { path: /healthz, port: http }, periodSeconds: 10 }
              readinessProbe: { httpGet: { path: /readyz, port: http }, periodSeconds: 5 }
              lifecycle:
                preStop: { exec: { command: ["sleep", "5"] } }
              resources:
                {{- toYaml .Values.resources | nindent 12 }}
    
  7. Создай helm/notes/templates/service.yaml:

    apiVersion: v1
    kind: Service
    metadata:
      name: {{ .Release.Name }}
      labels:
        {{- include "notes.labels" . | nindent 4 }}
    spec:
      type: ClusterIP
      selector:
        {{- include "notes.selectorLabels" . | nindent 4 }}
      ports:
        - name: http
          port: 8080
          targetPort: http
    
  8. Создай helm/notes/templates/httproute.yaml:

    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: {{ .Release.Name }}
      labels:
        {{- include "notes.labels" . | nindent 4 }}
    spec:
      parentRefs:
        - name: {{ .Values.gateway.name }}
      hostnames:
        - {{ required "нужен gateway.host" .Values.gateway.host | quote }}
      rules:
        - backendRefs:
            - name: {{ .Release.Name }}
              port: 8080
    

    Что здесь важно (всё, кроме двух пунктов, разобрано в теории):

    • checksum/config это аннотация пода. Значение это хеш (sha256sum) готового ConfigMap. Изменился конфиг, хеш другой, шаблон пода другой, и Kubernetes сам перезапускает поды. Без неё поды, прочитавшие переменные при старте, остались бы со старым конфигом.
    • $.Template.BasePath даёт путь к каталогу templates (символ $ это корневой контекст: внутри range и with точка меняется, а $ нет), и include (print ...) рендерит соседний шаблон, чтобы посчитать его хеш.
    • Селектор Deployment (selectorLabels) содержит только name: notes. Метки в labels меняются от релиза к релизу (версия, имя релиза), а селектор у существующего Deployment менять нельзя, иначе helm upgrade упадёт с ошибкой про неизменяемое поле selector.
  9. Проверь чарт и отрисуй его. Разбор: helm lint helm/notes проверяет чарт статически; в helm template notes helm/notes -n notes -f ... первое notes это имя релиза, второе путь к чарту, -n namespace, -f файл значений; grep -E '^kind|replicas:|image:|LOG_LEVEL' оставляет только строки с этими словами (-E расширенные регулярки, ^ начало строки, | «или»):

    helm lint helm/notes
    helm template notes helm/notes -n notes -f helm/notes/values-dev.yaml | grep -E '^kind|replicas:|image:|LOG_LEVEL'
    

Что должно получиться:

==> Linting helm/notes
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed
kind: ConfigMap
  LOG_LEVEL: "debug"
kind: Service
kind: Deployment
  replicas: 2
          image: "ghcr.io/CHANGE_ME/notes:0.4.1"
kind: HTTPRoute

Как читать вывод: первые три строки это итог helm lint: icon is recommended лишь совет (иконка чарта для каталогов), не ошибка; важна последняя строка 0 chart(s) failed. Дальше идут только те строки helm template, которые пропустил grep. Helm выводит объекты в своём порядке (ConfigMap и Service раньше Deployment), не в порядке файлов. LOG_LEVEL: "debug" пришёл из values-dev.yaml, replicas: 2 тоже, а тег 0.4.1 взят из appVersion, потому что image.tag пуст. Значение CHANGE_ME в образе ты заменил своим именем в шаге 2, у тебя будет оно.

Объясни себе:

  • Почему селектор Deployment вынесен в отдельный хелпер без instance и версии?
  • Что делает checksum/config и почему в нём include того же ConfigMap?

Типичные ошибки:

  • Error: notes/templates/deployment.yaml:27:28 и дальше строки executing "notes/templates/deployment.yaml" at <.Values.image.repository>: и nil pointer evaluating interface {}.repository: пропал целый блок (здесь image), а шаблон берёт у него вложенный ключ. Сверь values.yaml, имена чувствительны к регистру. Если пропал одиночный верхнеуровневый ключ (например replicaCount), ошибки не будет: Helm молча подставит пустое значение (replicas: без числа). Для обязательных значений используй required.
  • Error: parse error at (notes/templates/deployment.yaml:5): unexpected "}" in operand: в шаблоне лишняя или потерянная скобка }}.
  • Error: YAML parse error on notes/templates/deployment.yaml: error converting YAML to JSON: yaml: line 12: did not find expected key: сдвиг после nindent неверный, сравни число пробелов с уровнем вложенности.

Задание 3. Переезд на Helm и обновление

Цель: заменить ручные манифесты релизом, затем обновить значения и посмотреть, как Pod’ы перезапускаются по хешу конфига.

Предскажи: что скажет Helm, если запустить helm install при живых объектах Deployment notes из kubectl apply?

Ответ

Откажется: invalid ownership metadata. Helm не берёт под контроль чужие объекты без меток и аннотаций владения. Есть два пути: усыновить (добавить метки и аннотации руками) или удалить старые и поставить релиз. Мы выбираем второе: это учебный кластер, и короткий простой допустим. На проде так не делают, там усыновляют или ставят релиз под другим именем и переключают трафик.

Разбор команд: kubectl delete -f файл удаляет объекты, описанные в файле; git rm удаляет файл и сразу готовит это удаление для коммита. --timeout 3m ограничивает ожидание, --rollback-on-failure при неудаче сам откатывает релиз. kubectl get pods -w (-w от watch) не завершается, а печатает изменения по мере появления.

Шаги:

  1. Удали app-манифесты и убери их из репозитория (Secret, Gateway и Postgres не трогаем):

    kubectl -n notes delete -f k8s/base/10-deployment.yaml -f k8s/base/20-service.yaml \
      -f k8s/base/32-httproute.yaml -f k8s/base/50-configmap.yaml
    git rm k8s/base/10-deployment.yaml k8s/base/20-service.yaml \
      k8s/base/32-httproute.yaml k8s/base/50-configmap.yaml
    
  2. Установи релиз и дождись готовности. --rollback-on-failure откатит установку при неудаче (в Helm 3 и старых статьях этот флаг называется --atomic):

    helm upgrade --install notes helm/notes -n notes -f helm/notes/values-dev.yaml --rollback-on-failure --timeout 3m
    helm list -n notes
    kubectl -n notes get deploy,svc,httproute
    
  3. Поменяй уровень логов через --set и снова обнови релиз. Следи за Pod’ами в соседнем терминале (kubectl -n notes get pods -w):

    helm upgrade notes helm/notes -n notes -f helm/notes/values-dev.yaml --set config.LOG_LEVEL=warning --rollback-on-failure
    helm history notes -n notes
    helm get values notes -n notes
    

Что должно получиться (формат примерный: на кластере вывод не прогонялся, даты и хеши у тебя будут свои):

NAME    NAMESPACE  REVISION  STATUS    CHART        APP VERSION
notes   notes      1         deployed  notes-0.1.0  0.4.1
REVISION  UPDATED                   STATUS      CHART        APP VERSION  DESCRIPTION
1         Tue Sep 29 10:15:02 2026  superseded  notes-0.1.0  0.4.1        Install complete
2         Tue Sep 29 10:17:40 2026  deployed    notes-0.1.0  0.4.1        Upgrade complete
USER-SUPPLIED VALUES:
config:
  LOG_LEVEL: warning
replicaCount: 2

Во втором терминале видно, как старые Pod’ы заменяются новыми по одному: maxUnavailable: 0.

Как читать вывод: в helm list колонка REVISION растёт с каждым обновлением, STATUS deployed значит «текущая ревизия применена». В helm history предыдущая ревизия стала superseded («заменена»). Колонка UPDATED у тебя будет с твоим временем (в helm list она тоже есть, мы её здесь опустили для краткости). helm get values показывает только то, что ты передал: replicaCount: 2 из файла и LOG_LEVEL: warning из --set, но не умолчания из values.yaml. Чтобы увидеть всё, добавь --all.

Объясни себе:

  • Почему во второй ревизии Pod’ы пересоздались, хотя образ не менялся?
  • Чем --set опасен для воспроизводимости по сравнению с файлом значений?

Типичные ошибки:

  • Error: INSTALLATION FAILED: unable to continue with install: Deployment "notes" in namespace "notes" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; ... (дальше идут ещё аннотации meta.helm.sh/...): старые объекты не удалены. Удали их (шаг 1) или усынови.
  • Error: UPGRADE FAILED: release notes failed, and has been rolled back due to rollback-on-failure being set: resource Deployment/notes/notes not ready ... (в конце будет context deadline exceeded): Pod’ы не стали готовыми за 3 минуты. --rollback-on-failure откатит сам, причину ищи в kubectl -n notes describe pod (обычно неверный образ или пустой Secret).
  • Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: resource mapping not found for name: "notes" namespace: "notes" from "": no matches for kind "HTTPRoute" in version "gateway.networking.k8s.io/v1" и строка ensure CRDs are installed first: не установлены CRD Gateway API (урок 5.4).

Задание 4. Откат и hooks

Цель: намеренно выкатить плохую версию и откатиться.

Предскажи: если выкатить несуществующий тег образа без --rollback-on-failure, что покажет helm list: deployed или failed? Что будет с трафиком?

Ответ

Без --wait Helm считает установку успешной, как только API принял объекты: статус deployed. Новые Pod’ы будут в ImagePullBackOff, но благодаря maxUnavailable: 0 и readiness-пробе старые продолжат обслуживать трафик. Это ещё одна причина писать --rollback-on-failure или --wait в CI: иначе статус релиза лжёт.

Разбор команд: --set image.tag=9.9.9 задаёт тег, которого нет в реестре; curl -sk тихо (-s) обращается к https, не проверяя сертификат (-k, у нас самоподписанный). helm rollback notes 2 -n notes --wait возвращает манифест ревизии 2 и ждёт готовности.

Шаги:

  1. Выкати несуществующий тег:

    helm upgrade notes helm/notes -n notes -f helm/notes/values-dev.yaml --set image.tag=9.9.9
    kubectl -n notes get pods -l app.kubernetes.io/name=notes
    curl -sk -o /dev/null -w '%{http_code}\n' https://notes.lab/healthz
    

    Для curl нужна запись notes.lab в /etc/hosts, её настраивали в уроке 5.4. Новый под появится не мгновенно: сначала ContainerCreating, потом ErrImagePull. Подожди 20-30 секунд и повтори get pods (или добавь -w), пока не увидишь ImagePullBackOff.

  2. Откатись на прошлую ревизию и посмотри историю:

    helm history notes -n notes
    helm rollback notes 2 -n notes --wait
    helm history notes -n notes
    

Что должно получиться (формат примерный: на кластере вывод не прогонялся, хеши в именах подов у тебя будут свои):

NAME                     READY   STATUS             RESTARTS   AGE
notes-6d9c7b8f54-x2k7p   0/1     ImagePullBackOff   0          20s
notes-7f5c9d6b48-abcde   1/1     Running            0          3m
notes-7f5c9d6b48-fghij   1/1     Running            0          3m
REVISION  UPDATED                   STATUS      CHART        APP VERSION  DESCRIPTION
1         Tue Sep 29 10:15:02 2026  superseded  notes-0.1.0  0.4.1        Install complete
2         Tue Sep 29 10:17:40 2026  superseded  notes-0.1.0  0.4.1        Upgrade complete
3         Tue Sep 29 10:21:05 2026  superseded  notes-0.1.0  0.4.1        Upgrade complete
4         Tue Sep 29 10:22:31 2026  deployed    notes-0.1.0  0.4.1        Rollback to 2

Это вывод второго helm history, после отката. А curl на шаге 1 печатает код ответа:

200

Код 200 значит, что старые Pod’ы живы и отвечают. Ключи -o /dev/null выбрасывают тело ответа, -w '%{http_code}\n' печатает только код.

Как читать вывод: у нового пода ImagePullBackOff: Kubernetes не смог скачать образ и ждёт с нарастающими паузами. Два старых пода Running: пока новый не станет Ready, старые не удаляются (maxUnavailable: 0). В истории после отката нет ревизии со статусом «плохая» в последней строке: ревизия 3 осталась superseded, а deployed теперь ревизия 4 с описанием Rollback to 2.

Объясни себе:

  • Почему откат создал ревизию 4, а не вернул счётчик на 2?
  • Зачем --rollback-on-failure в CI, если есть ручной rollback?

Типичные ошибки:

  • Error: release has no 99 version (для helm rollback notes 99): указан номер ревизии, которой нет в helm history.

Задание 5. Шаг проекта: чарт в репозитории

Цель: зафиксировать чарт 0.1.0 в git и проверить, что платформенные манифесты остались в k8s/base/.

Предскажи: какие файлы остались в k8s/base/ и почему helm uninstall notes не удалит Postgres?

Ответ

Остались 00-namespace, 30-envoyproxy, 31-gateway, 40-postgres, 60-pg-backup-cronjob (плюс 70-netpol... появится позже). Postgres не входит в релиз: helm uninstall удаляет только объекты, которые Helm сам создал и записал в манифест релиза.

Шаги:

  1. Поставь kubeconform (отдельная небольшая программа, в Helm она не входит). Скачиваем архив и файл контрольных сумм релиза v0.8.0, grep linux-amd64 оставляет из файла только строку нашего архива, sha256sum -c - проверяет её (- значит «читай строки из потока»), дальше распаковка и установка, как с Helm в задании 1 (для ARM замени amd64 на arm64; на macOS проще brew install kubeconform):

    cd /tmp
    curl -fsSLO https://github.com/yannh/kubeconform/releases/download/v0.8.0/kubeconform-linux-amd64.tar.gz
    curl -fsSLO https://github.com/yannh/kubeconform/releases/download/v0.8.0/CHECKSUMS
    grep linux-amd64 CHECKSUMS | sha256sum -c -
    tar -xzf kubeconform-linux-amd64.tar.gz
    sudo install kubeconform /usr/local/bin/
    kubeconform -v
    cd ~/notes
    

    Ожидаемо: строка kubeconform-linux-amd64.tar.gz: OK и версия v0.8.0.

  2. Проверь чарт на схему Kubernetes. kubeconform сверяет YAML со схемами объектов Kubernetes (-strict ругается на лишние поля, -summary печатает итог, -ignore-missing-schemas пропускает объекты, схемы которых он не знает); читает он из stdin, поэтому вывод helm template передаётся через |:

    helm template notes helm/notes -n notes | kubeconform -strict -ignore-missing-schemas -summary
    
  3. Проверь состав k8s/base/, убедись, что в чарте нет секретов, и только потом зафиксируй всё в git. Порядок важен: секрет, попавший в коммит, остаётся в истории, и убрать его можно только переписыванием истории.

    ls k8s/base/
    grep -rniE "password|postgres(ql)?://" helm/notes || echo "секретов в чарте нет"
    git add helm/notes k8s/base && git commit -m "helm: чарт notes 0.1.0, приложение переехало из k8s/base"
    

    Команда ищет слово password и адреса вида postgresql://, то есть настоящие значения. Имя ключа DATABASE_URL в чарте есть (это ссылка на Secret), поэтому по нему не ищем: оно не означает утечку. Такой grep ловит только очевидное. Настоящую защиту ставят автоматически: gitleaks или pre-commit-хук, которые не дают закоммитить секрет.

Что должно получиться:

kubeconform-linux-amd64.tar.gz: OK
v0.8.0
Summary: 4 resources found parsing stdin - Valid: 3, Invalid: 0, Errors: 0, Skipped: 1
00-namespace.yaml
30-envoyproxy.yaml
31-gateway.yaml
40-postgres.yaml
60-pg-backup-cronjob.yaml
секретов в чарте нет

Как читать вывод: Valid: 3 это ConfigMap, Service и Deployment; Skipped: 1 это HTTPRoute, у kubeconform нет схемы для CRD (расширения Kubernetes, поэтому -ignore-missing-schemas). Если бы в шаблоне были лишние поля, появилась бы строка вроде Deployment notes is invalid: ... additional properties 'limits', 'requests' not allowed (этот текст получен на настоящем прогоне с неверным nindent).

Объясни себе:

  • Почему helm lint прошёл бы и с неверной apiVersion, а kubeconform нет?
  • Почему Secret notes-db вне чарта и как чарт узнаёт его имя?

Типичные ошибки:

  • Error: validation: chart.metadata.version is required (helm lint добавит [ERROR] Chart.yaml: version is required): в Chart.yaml нет version, сверь с заданием 2.

Задание 6. Чужой чарт: версия, значения, откат

Цель: поставить готовый чарт из репозитория так, как это делают на работе: с закреплённой версией, своими значениями и откатом. Берём учебный чарт podinfo (маленькое веб-приложение, его часто используют для проверок), в namespace podinfo-demo, чтобы не задеть «Заметки».

Предскажи: что случится, если поставить чужой чарт без --version?

Ответ

Helm возьмёт самую свежую версию из репозитория. Сегодня она одна, через месяц другая, и тот же скрипт поставит уже другое. Поэтому в CI и в рабочих командах версию чарта закрепляют.

Разбор команд: helm repo add имя URL запоминает адрес репозитория чартов, helm repo update скачивает его свежий список. helm search repo ... --versions показывает доступные версии чарта. helm show values печатает значения по умолчанию, то есть «какие пропуски можно заполнить». helm get values показывает то, что передал ты, а helm get manifest готовый YAML, который Helm отправил в кластер.

Шаги:

  1. Добавь репозиторий и посмотри версии и значения:

    helm repo add podinfo https://stefanprodan.github.io/podinfo
    helm repo update
    helm search repo podinfo/podinfo --versions | head -5
    helm show values podinfo/podinfo | head -30
    
  2. Сохрани два своих значения в файл и поставь чарт, закрепив версию (подставь версию из search, 6.7.1 взята как пример):

    printf 'replicaCount: 2\nui:\n  message: "привет из чужого чарта"\n' > /tmp/podinfo-values.yaml
    helm install podinfo podinfo/podinfo --version 6.7.1 -n podinfo-demo --create-namespace -f /tmp/podinfo-values.yaml --wait --timeout 3m
    helm get values podinfo -n podinfo-demo
    helm get manifest podinfo -n podinfo-demo | grep -E '^kind|replicas:|PODINFO_UI_MESSAGE'
    
  3. Обнови значение разовым --set, откатись на ревизию 1 и убери за собой:

    helm upgrade podinfo podinfo/podinfo --version 6.7.1 -n podinfo-demo -f /tmp/podinfo-values.yaml --set replicaCount=3 --wait
    helm history podinfo -n podinfo-demo
    helm rollback podinfo 1 -n podinfo-demo --wait
    helm uninstall podinfo -n podinfo-demo
    kubectl delete namespace podinfo-demo
    rm /tmp/podinfo-values.yaml
    

Что должно получиться (формат примерный: на кластере вывод не прогонялся, версии и даты у тебя будут свои):

USER-SUPPLIED VALUES:
replicaCount: 2
ui:
  message: привет из чужого чарта
REVISION  STATUS      CHART          DESCRIPTION
1         superseded  podinfo-6.7.1  Install complete
2         deployed    podinfo-6.7.1  Upgrade complete

Как читать вывод: USER-SUPPLIED VALUES содержит только твои два значения, остальное берётся из умолчаний чарта (helm show values). Откат на ревизию 1 вернёт replicaCount: 2 и создаст ревизию 3, как в задании 4.

Объясни себе:

  • Зачем закреплять --version, если чарт «и так тот же»?
  • Чем helm get values отличается от helm get manifest и когда нужен второй?

Типичные ошибки:

  • Error: INSTALLATION FAILED: chart "podinfo" matching 6.7.1 not found in podinfo index: такой версии нет, выбери из helm search repo podinfo/podinfo --versions.
  • Error: no repository definition for podinfo: не выполнен helm repo add.

Нейросеть может предложить флаг Helm, которого нет в твоей версии. Сверь любой флаг с helm upgrade –help и прогони helm template и kubeconform до установки.

Сломай и почини

Скрипт ломает чарт в ~/notes/helm/notes, кластер не трогает. Скачай его, сверь контрольную сумму (как с Helm в задании 1) и запусти с номером сценария 1, 2 или 3. Запускай без sudo. Сумма защищает только от обрыва загрузки, но не от подмены файла в репозитории: на работе чужие скрипты сначала читают и только потом запускают. Здесь скрипт короткий, его можно прочесть сразу, но интереснее сначала найти причину сам, а прочесть после решения: так видно, как именно сделана поломка.

curl -fsSL -o /tmp/break-5.9.sh https://raw.githubusercontent.com/distinguished-sre/learning/main/devops/project/notes/break/5.9/break.sh
echo "730cb7b37698ab42fe65d8e9cb5a5bb7342f25a6092f30f2046f047ef84c30b5  /tmp/break-5.9.sh" | sha256sum -c -
bash /tmp/break-5.9.sh 1

Перед первой правкой скрипт сохраняет копии файлов в ~/.cache/break-5.9, а bash /tmp/break-5.9.sh fix возвращает чарт в исходное состояние (безопасно запускать повторно).

Симптом

Ты запускаешь helm template notes helm/notes (или helm install), и Helm возвращает ошибку вместо YAML. Записывай точный текст: он и есть первая подсказка. Сценарии дают три разные ошибки.

Гипотезы

Шаблон обращается к ключу, которого нет в values; YAML после подстановки сломан отступами; обязательное значение пустое; релиз с таким именем уже есть.

Проверки

helm lint helm/notes                                # ловит часть ошибок статически
helm template notes helm/notes --debug | tail -30   # --debug печатает результат даже при неверном YAML
helm list -A --all                                  # релизы всех namespace, в том числе failed и pending

В ошибке читай три вещи: файл шаблона (notes/templates/deployment.yaml), строку и столбец (27:28), выражение в угловых скобках (<.Values.image.repository>).

Исправление

Разбор всех сценариев
  1. Из values.yaml пропал блок image. Ошибка:

    Error: notes/templates/deployment.yaml:27:28
      executing "notes/templates/deployment.yaml" at <.Values.image.repository>:
        nil pointer evaluating interface {}.repository
    

    Шаблон просит .Values.image.repository, а ключа image нет: Helm не может взять поле у «ничего» (nil pointer). Верни блок image в values.yaml (или запусти fix). Чтобы шаблон был защищён, значения без разумной пустоты надо описывать через required.

  2. Вместо nindent 12 стоит indent 12, и перед блоком resources нет перевода строки. Ошибка:

    Error: YAML parse error on notes/templates/deployment.yaml: error converting YAML to JSON: yaml: line 56: did not find expected key
    

    Номер строки относится к готовому YAML, а не к шаблону. Найди место через helm template --debug: блок requests склеился со строкой resources:. Верни {{- toYaml .Values.resources | nindent 12 }}.

  3. В values.yaml пустой gateway.host. Ошибка:

    Error: execution error at (notes/templates/httproute.yaml:11:9): нужен gateway.host
    

    Это сообщение из твоего же required: так и задумано, рендер остановился до обращения к кластеру. Задай gateway.host в values.yaml или через --set gateway.host=notes.lab.

Отдельный частый случай без скрипта: Error: INSTALLATION FAILED: cannot reuse a name that is still in use. Релиз notes уже существует, в том числе в статусе failed. Смотри helm list -A --all, затем либо helm upgrade --install, либо helm uninstall notes -n notes.

Общий приём: helm lint, затем helm template --debug, kubeconform, и только потом install.

ИИ в помощь

Нейросеть хорошо объясняет шаблоны Helm и находит опечатки в них, но не видит твой кластер и может выдумать флаги или поля. Общие правила: ИИ-помощник.

Задача: разобрать шаблон, который отрендерился странно.

Я учу Helm. Вот кусок шаблона и вывод helm template:
<вставь шаблон и вывод без паролей>
Объясни, откуда взялся каждый отступ и каждое значение, и где вероятная ошибка в nindent или в путях values.

Проверь ответ: запусти helm template с правкой и сверь отступы с теорией про nindent, а потом прогони вывод через kubeconform. Типичная ошибка: нейросеть советует число для nindent «на глаз», не посчитав глубину.

Задача: разобраться с приоритетом значений.

Вот values.yaml, values-dev.yaml и команда helm template с флагами -f и --set:
<вставь файлы и команду без паролей>
Посчитай итоговое значение каждого ключа и скажи, какой слой победил.

Проверь ответ: выведи итог командой helm template или helm get values --all и сравни с ответом. Типичная ошибка: нейросеть забывает, что значения в списках заменяются целиком, а не склеиваются.

Задача: объяснить ошибку установки.

helm upgrade --install вернул ошибку: <вставь текст ошибки>.
Объясни простыми словами, что это значит, и дай три проверки от самой дешёвой.

Проверь ответ: проверь каждый предложенный флаг в helm upgrade --help, а ошибку найди в разделе «Сломай и почини». Типичная ошибка: нейросеть советует --force или ручное удаление объектов, не спросив, что в них хранится.

Словарик урока

Термин Простыми словами
Манифест (manifest) YAML-файл с описанием объекта Kubernetes
Helm Программа на твоей машине: подставляет значения в шаблоны и ставит результат в кластер с историей
Чарт (chart) Каталог с шаблонами манифестов, значениями по умолчанию и паспортом Chart.yaml
Values (значения) Настройки, которые подставляются в пропуски шаблонов: values.yaml, -f, --set
Шаблон (template) Манифест с пропусками {{ ... }} на языке Go-шаблонов
Рендер (render) Подстановка значений в шаблоны, результат обычный YAML
Релиз (release) Установленный в кластер экземпляр чарта под именем
Ревизия (revision) Номер версии релиза; каждое обновление и откат создают новую
Хелпер (_helpers.tpl) Именованный кусок шаблона, который вызывают через include
nindent Функция: перевод строки и сдвиг каждой строки на N пробелов
required Функция: останавливает рендер с сообщением, если значение пусто
Идемпотентность Повторный запуск даёт тот же результат: upgrade --install
Хук (hook) Объект с аннотацией helm.sh/hook, запускается до или после операции
appVersion и version Версия приложения и версия самого чарта
Контрольная сумма (checksum) «Отпечаток» файла: меняется при любом изменении содержимого
OCI-реестр Хранилище чартов и образов с адресом oci://...
Реестр (registry) Склад с адресом, где лежат упакованные чарты или образы
helm lint и helm template Проверка чарта без кластера и печать готового YAML до установки
Оператор (operator) Программа в кластере, которая сама ухаживает за сложной системой, например базой
Откат (rollback) Возврат к прошлой рабочей версии
Тег образа (image tag) Метка версии образа, например 0.4.1
helm diff Плагин: показывает разницу между релизом в кластере и тем, что будет после upgrade
values.schema.json Файл чарта: описывает, какие значения бывают и каких типов, Helm проверяет по нему values
crds/ Каталог чарта с CRD: ставятся только при первой установке, при upgrade не обновляются
Subchart (зависимость) Чарт, от которого зависит другой чарт; описан в dependencies в Chart.yaml

Вопросы с собеседований

Раздел для повторения: ответь вслух, потом открой ответ. Короткие вопросы с пометкой [на скорость] тренируй на время: ответ за 30 секунд.

1. [junior] [часто] Что такое Helm, чарт и релиз и зачем это нужно?

Ответ

Helm - пакетный менеджер для Kubernetes. Чарт - это пакет: шаблоны манифестов плюс values.yaml со значениями по умолчанию. Релиз - конкретная установка чарта в кластер под своим именем, например helm install notes ./chart. Значения я переопределяю через -f values-prod.yaml или --set, а Helm рендерит шаблоны и применяет манифесты. Каждая операция Helm (helm upgrade, helm rollback) делает новую ревизию релиза, поэтому можно посмотреть историю helm history notes и откатиться helm rollback notes 1. Правки руками через kubectl ревизий не создают.

Что хотят услышать: чарт = шаблоны + values, релиз = установка, ревизии и откат, переиспользование одного чарта для разных окружений.

Красный флаг: путают чарт и релиз или говорят, что Helm просто «копирует YAML в кластер» без шаблонов и истории.

2. [junior] [часто] Ты выкатил релиз, приложение начало отдавать 500. Как откатиться?

Ответ

helm history notes показывает ревизии, helm rollback notes <ревизия> --wait возвращает нужную. Откат создаёт новую ревизию с содержимым старой. Потом разбираюсь в причине по логам.

Что хотят услышать: history, rollback, --wait, откат это новая ревизия; понимание, что откат не возвращает данные в БД и миграции.

Красный флаг: «сделаю kubectl edit и поправлю руками», после чего релиз расходится с реальностью.

3. [middle] [часто] Как передать разные настройки для dev и prod?

Ответ

Общий values.yaml с умолчаниями и по файлу на окружение: -f values-prod.yaml. Файлы лежат в git. --set только для разовых вещей, потому что он не воспроизводим. Секреты не в values.

Что хотят услышать: порядок приоритета, файлы в git, отдельные релизы или namespace, причина против --set; упоминание Kustomize как альтернативы (урок 5.10).

Красный флаг: отдельная копия чарта под каждое окружение.

4. [junior] Чем helm lint отличается от helm template?

Ответ

lint проверяет структуру чарта и выводит замечания, манифесты не печатает. template рендерит YAML и печатает его, кластер для этого не нужен. Использую оба: lint ловит структурные ошибки, template показывает, что реально уедет (с --debug печатает результат даже при сломанном YAML). В CI после template гоню kubeconform, который сверяет YAML со схемами Kubernetes, а helm upgrade --dry-run=server отправляет манифесты в API-сервер для проверки без создания объектов.

Что хотят услышать: template --debug, связка с kubeconform в CI, --dry-run=server (Helm отправляет манифесты в API-сервер для проверки, но ничего не создаёт), что ловит ошибки, которых не видно без кластера.

Красный флаг: «они одно и то же» или «проверяю только на проде».

5. [junior] [на скорость] Где Helm хранит состояние релиза?

Ответ

В Secret типа helm.sh/release.v1 в namespace релиза, по одному на ревизию. Серверной части в кластере нет.

Что хотят услышать: Secret, по ревизии, нет Tiller, --history-max ограничивает число.

Красный флаг: «в базе Helm» или «в etcd Helm-сервера».

6. [middle] Поменяли ConfigMap, сделали helm upgrade, а Pod’ы работают со старым конфигом. Почему?

Ответ

Переменные из ConfigMap читаются при старте контейнера, шаблон Pod не изменился, поэтому rolling update не запустился. Решение: аннотация checksum/config с хешем ConfigMap, тогда любое изменение конфига меняет шаблон Pod. Разово можно kubectl rollout restart.

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

Красный флаг: «Kubernetes сам подхватит».

7. [middle] На helm install ошибка invalid ownership metadata. Что это и что делать?

Ответ

Объект с таким именем уже есть и создан не Helm: у него нет меток и аннотаций app.kubernetes.io/managed-by: Helm и meta.helm.sh/release-name. Helm не трогает чужое. Варианты: удалить объект и установить, либо усыновить, дописав метки и аннотации, если простой недопустим. В Helm 4 усыновить можно и флагом --take-ownership у install и upgrade: он пропускает проверку аннотаций Helm.

Что хотят услышать: аннотации meta.helm.sh/release-name и release-namespace, вывод про миграцию с kubectl apply на Helm без простоя, флаг --take-ownership.

Красный флаг: --force-replace (раньше --force) без понимания, что он пересоздаёт объекты.

8. [middle] В чарте пароль БД. Что не так и как правильно?

Ответ

Значение попадёт в git, в helm get values и в Secret релиза, доступный всем, кто читает Secret’ы в namespace. Правильно: чарт ссылается на существующий Secret (existingSecret), а сам Secret создаёт другой механизм: External Secrets, SOPS, Sealed Secrets (урок 9.2).

Что хотят услышать: existingSecret, сравнение с внешним хранилищем, причина: values это не секретное хранилище.

Красный флаг: «зашифрую base64».

9. [junior] [на скорость] В чём разница между version и appVersion в Chart.yaml?

Ответ

version версия чарта (шаблонов), appVersion версия приложения. Поменял шаблон: растёт version. Вышел новый образ: меняется appVersion.

Что хотят услышать: пример, где изменилась только одна из них; SemVer.

Красный флаг: «это одно и то же».

10. [middle] Helm или Kustomize: что выберешь для своего сервиса?

Ответ

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

Что хотят услышать: оба подхода, критерии (шаблоны против патчей, история релизов), реальный опыт.

Красный флаг: «Helm всегда лучше» или «шаблоны никогда не нужны».

11. [middle] Что делают флаги –install, –wait и –atomic в helm upgrade?

Ответ

--install ставит релиз, если его ещё нет, поэтому одна команда подходит и для первого раза, и для обновления. --wait ждёт, пока ресурсы станут готовыми, и без него Helm может сообщить об успехе, когда поды ещё не поднялись. --atomic при неудаче автоматически откатывает релиз и включает ожидание. В Helm 4 этот флаг называется --rollback-on-failure, а --atomic ещё принимается, но устарел. Ещё задаю --timeout, чтобы CI не висел вечно.

Что хотят услышать: upgrade –install идемпотентен, wait ждёт готовности, atomic откатывает, timeout, в CI нужен осмысленный результат.

Красный флаг: Считать, что без –wait команда проверяет готовность подов.

12. [middle] [на скорость] Что такое Helm hooks и когда их применяют?

Ответ

Hook - это ресурс чарта (обычно Job) с аннотацией helm.sh/hook, который Helm запускает в определённый момент жизненного цикла: pre-install, pre-upgrade, post-install, pre-delete и другие. Типичный пример: миграция БД перед обновлением приложения как pre-upgrade Job. Нужно помнить, что ресурсы-хуки Helm не считает частью релиза и сам не удаляет после выполнения: для этого нужна helm.sh/hook-delete-policy (hook-succeeded/hook-failed) или TTL для Job. Без аннотации Helm лишь удаляет прежний ресурс перед повторным запуском хука. Если хук упал, обновление прерывается.

Что хотят услышать: аннотация helm.sh/hook, стадии, пример с миграцией, delete-policy, хук не входит в релиз.

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

Проверено на версиях

Проверено запуском на Mac (без кластера):

  • Helm v4.3.0: helm lint, helm template (в том числе --debug и сообщения об ошибках сценариев 1, 2, 3), helm create; флаги --rollback-on-failure, --wait, --dry-run=server, --history-max, --reuse-values, --reset-then-reuse-values, --server-side, --take-ownership, --force-replace сверены по helm upgrade --help и helm install --help, --atomic в этой версии выдаёт предупреждение об устаревании; helm plugin install по умолчанию проверяет подпись (--verify). Строка v4.3.0+gbec5b06 получена запуском helm version --short и совпадает с коммитом тега v4.3.0.
  • kubeconform v0.8.0: helm template ... | kubeconform -strict -ignore-missing-schemas -summary.
  • Скрипт break.sh: shellcheck без замечаний, сценарии 1, 2, 3 и fix (по два запуска подряд) прогнаны на копии чарта.

Не прогонялось (кластер не запускался): helm install, upgrade, rollback, history, list, get values, repo add и установка podinfo из задания 6, kubectl из практики и их вывод, скачивание и установка Helm. У таких блоков вывода стоит пометка «формат примерный»: формат взят из документации Helm. Версии kind v0.33.0, kubectl 1.37.1, Gateway API v1.6.1, Envoy Gateway v1.9.2, образ приложения 0.4.1 взяты из прежних уроков темы и не перепроверялись.

Итог урока: ты умеешь

  • умею объяснить, чем чарт, значения, релиз и ревизия отличаются друг от друга
  • умею установить Helm с проверкой SHA256 и узнать его версию
  • умею описать приложение как чарт: Chart.yaml, values.yaml, шаблоны, хелперы
  • умею читать {{ .Values... }}, default, required, range, toYaml | nindent и посчитать нужный отступ
  • умею отличить lint, template --debug, kubeconform и install, и проверить чарт до кластера
  • умею ставить и обновлять релиз командой upgrade --install --rollback-on-failure
  • умею смотреть history, get values и откатываться через rollback
  • умею поставить чужой чарт с закреплённой версией, посмотреть show values, get values, get manifest и откатить
  • умею развести значения по окружениям через -f и объяснить, почему --set хуже
  • умею объяснить, что входит в чарт, а что остаётся платформой, и почему секрет вне чарта
  • умею читать ошибки nil pointer, YAML parse error, cannot reuse a name, invalid ownership metadata
  • умею назвать, что ещё встретится в чужих чартах: helm diff, values.schema.json, crds/, --reuse-values, зависимости

Дальше: Урок 5.10: Kustomize: окружения без шаблонов

Проверь себя

Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.

Тест работает с включённым JavaScript.

тема 5 урок 5.9 4 ч курс 0/0 ← → уроки

Помоги улучшить курс

Что нужно изменить?