Семь готовых use-case'ов из официальной документации

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

Все предыдущие уроки M7 (1–7) — по отдельности каждая категория аннотаций и функций. Этот урок собирает их в семь готовых, целиком рабочих сценариев из официальной документации Nelm-аннотаций — каждый комбинирует несколько аннотаций для решения конкретной практической задачи.

Теория

Use case 1 — Job, который должен выполниться перед основным приложением

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

apiVersion: batch/v1
kind: Job
metadata:
  name: {{.Application.Instance.Name}}-db-migrate
  annotations:
    werf.io/delete-policy: before-creation
spec: ...
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{.Application.Instance.Name}}-app
  annotations:
    werf.io/deploy-dependency-migrate: state=ready,kind=Job,name={{.Application.Instance.Name}}-db-migrate
spec: ...

Разобрано полностью в M6 уроке 4. delete-policy: before-creation гарантирует пересоздание Job на каждом деплое, deploy-dependency — что Deployment дождётся успешного завершения именно этого Job.

Use case 2 — общий ресурс между несколькими релизами

1
2
3
4
5
6
7

apiVersion: v1
kind: Secret
metadata:
  name: shared-tls
  annotations:
    werf.io/ownership: anyone
type: kubernetes.io/tls

Разобрано в M6 уроке 5 — предотвращает удаление Secret при uninstall одного из нескольких релизов, использующих его совместно.

Use case 3 — зависимость от внешнего оператора (cert-manager)

1
2
3
4

metadata:
  annotations:
    cert.external-dependency.werf.io/resource: certificates.v1.cert-manager.io/app-tls
    cert.external-dependency.werf.io/name: app-tls-production

Разобрано в M6 уроке 6 — ожидание готовности ресурса, управляемого сторонним контроллером. Формат значения <id>.external-dependency.werf.io/resource — <kind>[.<version>.<group>]/<name> (как у deploy-dependency, а не key=value-пары): Nelm ожидает, что ресурс станет present и ready.

Use case 4 — защита данных на двух уровнях

1
2
3
4
5
6

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
  annotations:
    helm.sh/resource-policy: keep

Разобрано в M6 уроке 7 — в комбинации с reclaimPolicy: Retain на StorageClass.

Use case 5 — некритичный компонент, который не должен ронять весь деплой

1
2
3
4
5
6
7
8

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: {{.Application.Instance.Name}}-metrics-agent
  annotations:
    werf.io/fail-mode: IgnoreAndContinueDeployProcess
    werf.io/track-termination-mode: NonBlocking
spec: ...

Разобрано в M7 уроке 4.

Use case 6 — ресурс, создаваемый только при первой установке

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: ...

Разобрано в M7 уроке 3 — с явным акцентом на то, почему ownership: anyone здесь обязателен, а не опционален.

Use case 7 — медленно стартующий ресурс с большим образом

1
2
3
4
5
6
7
8
9

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: elasticsearch
  annotations:
    werf.io/no-activity-timeout: 20m
    werf.io/failures-allowed-per-replica: "3"
    werf.io/show-service-messages: "true"
spec: ...

Разобрано в M7 уроке 4 — комбинация продления таймаута, допуска рестартов и включения диагностических событий.

Почему эти семь сценариев покрывают подавляющее большинство реальных задач

Все семь use case’ов представляют собой комбинации из двух-трёх аннотаций разных категорий (порядок + владение, tracking + fail-mode, lifecycle + ownership) — редко встречается задача, для которой потребовалась бы аннотация в изоляции от остальных. Умение узнавать эти паттерны и комбинировать их — ключевой практический навык продвинутого разработчика Application, отличающий уверенное владение Nelm от простого знания списка отдельных аннотаций.

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

• Применять только одну аннотацию из пары там, где документация явно указывает комбинацию. Например, deploy-on: install без ownership: anyone (use case 6) — классическая ошибка, разобранная в M7 уроке 3.
• Копировать use case дословно, не адаптируя имена ресурсов под конкретный .Application.Instance.Name. В реальном пакете все имена ресурсов должны быть параметризованы через .Application.Instance.Name (M5 урок 4) для поддержки множественных инстансов.
• Изобретать собственную комбинацию аннотаций там, где уже есть готовый, протестированный паттерн из официальной документации. Прежде чем решать нестандартную задачу порядка/владения ресурсами, стоит свериться с этим списком — велика вероятность, что задача уже решена одним из семи готовых паттернов.

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

1

d8 k get all,pvc,secrets -n course-m6-umami -o custom-columns=NAME:.metadata.name,ANNOTATIONS:.metadata.annotations

Сопоставьте текущий набор аннотаций пакета Umami с семью use case’ами из теории — определите, какие паттерны уже применены, а какие стоило бы добавить (например, use case 5 для вспомогательных компонентов, если они появятся в вашем пакете).

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

Пройдитесь по templates/ пакета Umami и для каждого ресурса explicитно определите, к какому из семи use case’ов (если к какому-либо) он относится — задокументируйте это в комментариях YAML (# use-case: job-migration), формируя привычку осознанного применения паттернов, а не случайного копирования аннотаций.

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

Полный набор use case’ов — 📋 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.07 — Шаблонные функции Nelm целиком.
• Следующий урок: M7.09 — Четыре известных подводных камня.

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