Lifecycle-аннотации целиком

Что нужно знать перед уроком

M7 урок 2 — механизмы порядка, M6 уроки 4–5 — первое знакомство с delete-policy и ownership. Этот урок закрывает все lifecycle-аннотации: resource-policy, ownership, deploy-on (полный список из 12 значений), delete-policy (4 значения), delete-propagation (3 значения).

Теория

helm.sh/resource-policy: keep — защита от удаления Nelm/Helm

Разобрано в M6 уроке 7 на примере PVC — эта аннотация Helm (не Nelm-специфичная, работает и в ванильном Helm) исключает ресурс из операций удаления при uninstall или удалении блока из шаблона.

werf.io/ownership — множественное владение, и разные дефолты для разных типов ресурсов

Разобрано в M6 уроке 5 на значении anyone — сигнализирует Nelm, что релиз не единственный владелец ресурса, поэтому не следует удалять ресурс, если он перестал рендериться в конкретном релизе (он может по-прежнему рендериться в другом).

Важная деталь, которую легко упустить: дефолтное значение ownership разное для разных типов ресурсов. Для обычных манифестов (Deployment, Service, ConfigMap и т.д.) дефолт — release (единоличное владение, ресурс удаляется, если исчез из рендера). Для хуков (Helm hooks) и CRD в директории crds/ дефолт уже anyone — потому что и хуки, и crds/-ресурсы по своей природе часто рассчитаны на переживание отдельных релизов (CRD, например, обычно не должен исчезать только потому, что один из нескольких релизов, использующих этот CRD, был удалён). Явно указывать ownership: anyone вручную требуется только для обычных ресурсов, которым нужно нестандартное (для их типа) поведение — как в use case из M6 урока 5.

werf.io/deploy-on — полный список из 12 значений

1

werf.io/deploy-on: pre-install,upgrade,post-install

Допустимые значения: pre-install, install, post-install, pre-upgrade, upgrade, post-upgrade, pre-rollback, rollback, post-rollback, pre-uninstall, uninstall, post-uninstall. Значение по умолчанию (если аннотация не указана): install,upgrade,rollback — то есть обычный ресурс рендерится при первичной установке, при обновлении и при откате, но не при uninstall (естественно — иначе он был бы создан заново перед удалением) и не в pre-/post- фазах (эти фазы предназначены для хуков, а не основных ресурсов).

Ключевой use case — ресурс, который должен быть создан только при первой установке:

1
2
3
4
5
6
7
8

apiVersion: batch/v1
kind: Job
metadata:
  name: {{.Application.Instance.Name}}-init-data
  annotations:
    werf.io/deploy-on: install
    werf.io/ownership: anyone   # КРИТИЧНО
spec: ...

Если для ресурса указан deploy-on: install (без upgrade) и при этом ownership: release (значение по умолчанию — единоличное владение), при следующем upgrade ресурс не попадёт в рендер (потому что upgrade не входит в его deploy-on) — и Nelm, видя его отсутствие в новом рендере, попытается его удалить, интерпретируя это как «пользователь убрал этот ресурс из шаблонов». Именно поэтому werf.io/ownership: anyone в этом сценарии — не опциональная деталь, а обязательное условие, отменяющее удаление отсутствующего в рендере ресурса.

werf.io/delete-policy — управление таймингом удаления

Значения (могут комбинироваться через запятую):

before-creation-if-immutable — почему это дефолт для Job: у Job есть множество immutable-полей (spec.template, spec.selector и т.д.), и попытка kubectl apply/SSA к существующему Job с изменённым spec.template завершится ошибкой «field is immutable». Nelm по умолчанию перехватывает именно эту ошибку и автоматически пересоздаёт Job — но только при реальном конфликте, не при каждом деплое. Если нужна гарантия пересоздания при каждом деплое (типичный сценарий для миграционных Job — см. M6 урок 4), явно указывается before-creation.

werf.io/delete-propagation — стратегия каскадного удаления Kubernetes

Это прямое отражение стандартного механизма Kubernetes deletionPropagation (доступного и через kubectl delete --cascade=<foreground|background|orphan>), просто выраженное как декларативная аннотация манифеста вместо флага команды.

Частые ошибки и подводные камни

• Указать deploy-on: install без ownership: anyone. Это самая частая ошибка с deploy-on — при следующем upgrade ресурс будет молча удалён, потому что Nelm посчитает его убранным из шаблонов.
• Использовать before-creation-if-immutable (дефолт) для миграционного Job, ожидая пересоздания при КАЖДОМ деплое. Дефолтное поведение пересоздаёт Job только при реальном конфликте immutable-полей — если содержимое spec.template не изменилось (например, тот же образ и команда), Job не будет пересоздан, и миграция не выполнится повторно. Для гарантированного повторного выполнения нужен явный before-creation.
• Путать helm.sh/resource-policy: keep и werf.io/ownership: anyone. Первая защищает ресурс от удаления Nelm/Helm вообще (ресурс останется физически, даже если релиз полностью удалён), вторая — только предотвращает удаление, вызванное отсутствием ресурса в текущем рендере одного из НЕСКОЛЬКИХ релизов, использующих один и тот же ресурс.

Практика в кластере

1
2
3

d8 k get job umami-init-data -n course-m6-umami -o yaml | grep -A2 annotations
nelm release install -n course-m6-umami -r umami .    # повторный деплой
d8 k get job umami-init-data -n course-m6-umami        # проверьте, что Job не был удалён

Проверьте на практике, что происходит с Job, у которого deploy-on: install без ownership: anyone, при повторном upgrade — воспроизведите ошибку намеренно в тестовом namespace, затем исправьте её добавлением ownership: anyone.

Практика разработки

Добавьте в пакет Umami аннотацию werf.io/delete-policy: before-creation для Job-миграции (заменив дефолтное поведение before-creation-if-immutable), чтобы гарантировать выполнение миграции при каждом деплое независимо от того, изменилось ли содержимое Job.

Шпаргалка команд урока

Полная таблица lifecycle-аннотаций — 📋 nelm .

Вопросы для самопроверки

Рекомендуемая литература

Официальная документация

• Deckhouse — Nelm-аннотации для Application

Статьи и блоги

• Вышла werf 2.0: новый движок развёртывания Nelm — Flant на Habr.
• Представляем werf 1.0 stable: GitOps и Helm — Flant на Habr.
• GitLab + K8s + Werf — Habr.

Книги

• Matt Butcher, Matt Farina, Josh Dolitsky. Learning Helm. 2019. ISBN 978-1492036781.

Связанные материалы

• Предыдущий урок: M7.02 — Ordering и dependencies целиком.
• Следующий урок: M7.04 — Tracking-аннотации.

✓ Урок пройден — все вопросы самопроверки отвечены верно