Хуки чартов

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

• Загрузки ConfigMap или Secret перед загрузкой остальных чартов при установке.
• Выполнения Job для резервного копирования базы данных перед установкой нового чарта, а затем выполнения другого Job после обновления для восстановления данных.
• Запуска Job перед удалением релиза для корректного вывода сервиса из ротации.

Хуки работают как обычные шаблоны, но имеют специальные аннотации, которые указывают Helm обрабатывать их особым образом. В этом разделе рассматриваются основные паттерны использования хуков.

Доступные хуки

Определены следующие хуки:

Значение аннотации	Описание
pre-install	Выполняется после рендеринга шаблонов, но до создания каких-либо ресурсов в Kubernetes
post-install	Выполняется после загрузки всех ресурсов в Kubernetes
pre-delete	Выполняется при запросе на удаление до удаления каких-либо ресурсов из Kubernetes
post-delete	Выполняется при запросе на удаление после удаления всех ресурсов релиза
pre-upgrade	Выполняется при запросе на обновление после рендеринга шаблонов, но до обновления каких-либо ресурсов
post-upgrade	Выполняется при запросе на обновление после обновления всех ресурсов
pre-rollback	Выполняется при запросе на откат после рендеринга шаблонов, но до отката каких-либо ресурсов
post-rollback	Выполняется при запросе на откат после изменения всех ресурсов
test	Выполняется при вызове подкоманды Helm test (см. документацию по тестам)

Обратите внимание, что хук crd-install был удалён в Helm 3 в пользу директории crds/.

Хуки и жизненный цикл релиза

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

1. Пользователь запускает helm install foo
2. Вызывается API установки библиотеки Helm
3. После проверки библиотека рендерит шаблоны foo
4. Библиотека загружает полученные ресурсы в Kubernetes
5. Библиотека возвращает объект релиза (и другие данные) клиенту
6. Клиент завершает работу

Helm определяет два хука для жизненного цикла установки: pre-install и post-install. Если разработчик чарта foo реализует оба хука, жизненный цикл изменяется следующим образом:

1. Пользователь запускает helm install foo
2. Вызывается API установки библиотеки Helm
3. Устанавливаются CRD из директории crds/
4. После проверки библиотека рендерит шаблоны foo
5. Библиотека готовится к выполнению хуков pre-install (загружая ресурсы хуков в Kubernetes)
6. Библиотека сортирует хуки по весу (по умолчанию вес равен 0), затем по типу ресурса и, наконец, по имени в порядке возрастания
7. Библиотека загружает хук с наименьшим весом первым (от отрицательных к положительным)
8. Библиотека ждёт, пока хук не станет «Ready» (за исключением CRD)
9. Библиотека загружает полученные ресурсы в Kubernetes. Обратите внимание: если указан флаг --wait, библиотека будет ждать, пока все ресурсы не перейдут в состояние готовности, и не запустит хук post-install до их готовности.
10. Библиотека выполняет хук post-install (загружая ресурсы хука)
11. Библиотека ждёт, пока хук не станет «Ready»
12. Библиотека возвращает объект релиза (и другие данные) клиенту
13. Клиент завершает работу

Что означает ожидание готовности хука? Это зависит от типа ресурса, объявленного в хуке. Если ресурс имеет тип Job или Pod, Helm будет ждать его успешного завершения. Если хук завершается с ошибкой, релиз также завершится с ошибкой. Это блокирующая операция, поэтому клиент Helm приостановит выполнение на время работы Job.

Для всех остальных типов ресурсов, как только Kubernetes отметит ресурс как загруженный (добавленный или обновлённый), он считается готовым («Ready»). Когда в хуке объявлено много ресурсов, они выполняются последовательно. Если у них есть веса (см. ниже), они выполняются в порядке весов. Начиная с Helm 3.2.0, ресурсы хуков с одинаковым весом устанавливаются в том же порядке, что и обычные ресурсы без хуков. В противном случае порядок не гарантируется. (В Helm 2.3.0 и новее они сортируются по алфавиту. Однако это поведение не является обязательным и может измениться в будущем.) Рекомендуется указывать вес хука и устанавливать его в 0, если порядок не важен.

Ресурсы хуков не управляются вместе с релизами

Ресурсы, создаваемые хуком, в настоящее время не отслеживаются и не управляются как часть релиза. После того как Helm убедится, что хук достиг состояния готовности, он оставляет ресурс хука без изменений. Сборка мусора для ресурсов хуков при удалении соответствующего релиза может быть добавлена в Helm 3 в будущем, поэтому любые ресурсы хуков, которые не должны удаляться, следует аннотировать с помощью helm.sh/resource-policy: keep.

На практике это означает, что если вы создаёте ресурсы в хуке, вы не можете полагаться на helm uninstall для их удаления. Чтобы удалить такие ресурсы, вам нужно либо добавить аннотацию helm.sh/hook-delete-policy в файл шаблона хука, либо установить поле времени жизни (TTL) для ресурса Job.

Написание хука

Хуки — это обычные файлы манифестов Kubernetes со специальными аннотациями в секции metadata. Поскольку они являются файлами шаблонов, вы можете использовать все стандартные возможности шаблонизации, включая чтение .Values, .Release и .Template.

Например, этот шаблон, сохранённый в templates/post-install-job.yaml, объявляет Job, который будет выполнен после установки (post-install):

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}"
  labels:
    app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
    app.kubernetes.io/instance: {{ .Release.Name | quote }}
    app.kubernetes.io/version: {{ .Chart.AppVersion }}
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  annotations:
    # This is what defines this resource as a hook. Without this line, the
    # job is considered part of the release.
    "helm.sh/hook": post-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    metadata:
      name: "{{ .Release.Name }}"
      labels:
        app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
        app.kubernetes.io/instance: {{ .Release.Name | quote }}
        helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
    spec:
      restartPolicy: Never
      containers:
      - name: post-install-job
        image: "alpine:3.3"
        command: ["/bin/sleep","{{ default "10" .Values.sleepyTime }}"]

Что делает этот шаблон хуком — это аннотация:

annotations:
  "helm.sh/hook": post-install

Один ресурс может реализовывать несколько хуков:

annotations:
  "helm.sh/hook": post-install,post-upgrade

Аналогично, нет ограничений на количество ресурсов, которые могут реализовывать один хук. Например, можно объявить и Secret, и ConfigMap как хуки pre-install.

Когда субчарты объявляют хуки, они также обрабатываются. Родительский чарт не может отключить хуки, объявленные в субчартах.

Можно определить вес хука, который поможет установить детерминированный порядок выполнения. Вес определяется с помощью следующей аннотации:

annotations:
  "helm.sh/hook-weight": "5"

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

Политики удаления хуков

Можно определить политики, определяющие, когда удалять соответствующие ресурсы хуков. Политики удаления хуков определяются с помощью следующей аннотации:

annotations:
  "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

Вы можете выбрать одно или несколько значений аннотации:

Значение аннотации	Описание
before-hook-creation	Удалить предыдущий ресурс перед запуском нового хука (по умолчанию)
hook-succeeded	Удалить ресурс после успешного выполнения хука
hook-failed	Удалить ресурс, если хук завершился с ошибкой

Если аннотация политики удаления хука не указана, по умолчанию применяется поведение before-hook-creation.