Три стадии Nelm подробно

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

M4 урок 3 — Server-Side Apply как основа механики Nelm. Здесь — как весь процесс деплоя релиза разбивается на три последовательные стадии, каждая со своей ответственностью. Это краткий обзор; полная таблица «аннотация → на какую стадию влияет» — в M7 уроке 1.

Теория

Render → Plan → Apply — три независимые стадии

Render — превращение шаблонов чарта (templates/*.yaml + .Values/.Release/.Chart/.Capabilities из M4 урока 1) в конечный набор YAML-манифестов. На этой стадии нет полноценного доступа к кластеру, за одним важным исключением — функция lookup (может обратиться к кластеру для чтения существующих ресурсов прямо во время рендера, что создаёт определённые риски таймингов, разбираем подробно в M7 уроке 9). Именно на этой стадии работают шаблонные debug-функции (dump_debug/printf_debug/include_debug/tpl_debug — M7 урок 7) и расшифровка .helm/secret-values.yaml/.helm/secret/ (M4 урок 2) — секреты расшифровываются в памяти именно на этапе Render, чтобы получить финальный текст манифеста с реальными (не зашифрованными) значениями.

Plan — подключение к кластеру: для каждого отрендеренного манифеста выполняется dry-run Server-Side Apply (M4 урок 3), сервер вычисляет точный diff между желаемым и текущим состоянием без реального применения. На основе всех diff’ов строится DAG (directed acyclic graph — направленный ациклический граф) операций create/update/delete, учитывающий аннотации порядка (werf.io/weight, werf.io/deploy-dependency-* — полная таблица в M7 уроке 2). Именно на этой стадии Nelm определяет, что и в каком порядке нужно менять — но ничего ещё не меняется в реальности.

Apply — фактическое выполнение построенного DAG: операции без взаимных зависимостей выполняются параллельно (там, где DAG это позволяет), с зависимостями — строго последовательно согласно графу. На этой стадии работает трекинг готовности (сначала посмотрим за прогрессом Deployment/Job/StatefulSet через track-termination-mode — M7 урок 4) и стриминг логов контейнеров прямо в вывод команды деплоя (log-*-аннотации — M7 урок 5).

Почему разделение на три стадии критично для надёжности

Каждая стадия решает свою задачу изолированно: ошибка шаблонизации (Render) выявляется до любого обращения к кластеру — не оставляя кластер в промежуточном состоянии. Ошибка на стадии Plan (например, невалидный манифест, отвергнутый API-сервером при dry-run) выявляется до реального применения — снова без побочных эффектов в кластере. Только Apply реально меняет состояние кластера, и к этому моменту Nelm уже точно знает весь план изменений целиком. Эта изоляция — прямое архитектурное следствие перехода на SSA: без точного dry-run на стадии Plan невозможно было бы гарантировать, что реальный Apply пройдёт именно так, как ожидается.

Связь с командой nelm release plan install

Команда nelm release plan install (M4 урок 3) — это буквально выполнение первых двух стадий (Render + Plan) без третьей (Apply) — вы получаете точный план изменений, ничего не применяя в реальности. nelm release install выполняет все три стадии подряд, автоматически.

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

• Пытаться использовать полноценные обращения к кластеру (кроме lookup) на стадии Render. Render — это чистая шаблонизация с ограниченным доступом к кластеру; вся полноценная работа с реальным состоянием — стадии Plan/Apply.
• Ожидать, что параллельность на Apply означает полный отказ от порядка. DAG учитывает зависимости — параллельно выполняются только те операции, между которыми нет зависимостей (по весу, deploy-dependency и подобным аннотациям, M7 урок 2); там, где зависимость есть, порядок строго сохраняется.
• Не различать ошибку Render (шаблонизация) и ошибку Plan (валидация API-сервером). Диагностика отличается: ошибка Render — проблема в самом шаблоне/values, ошибка Plan — обычно проблема в валидности итогового манифеста относительно API-схемы кластера.

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

Практики в кластере в этом уроке нет — фокус на теоретической модели, первая полноценная установка — с M4 урока 5.

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

Пронаблюдайте все три стадии на чарте Vikunja из предыдущих уроков M4 отдельными командами:

1
2
3
4
5
6
7
8

# Стадия 1: Render — только шаблонизация, без кластера
nelm chart render . -r vikunja-demo

# Стадии 1+2: Render + Plan — точный diff без применения
nelm release plan install -n course-m4-vikunja -r vikunja-demo .

# Все три стадии: Render + Plan + Apply — реальное применение
nelm release install -n course-m4-vikunja -r vikunja-demo .

Сравните вывод каждой команды — обратите внимание, что chart render не требует доступа к кластеру вообще (можно выполнить даже без настроенного kubectl-контекста, если в шаблонах не используется lookup), а plan install/release install требуют.

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

1
2
3

nelm chart render <chart-dir> -r <release>
nelm release plan install -n <ns> -r <release> <chart-dir>
nelm release install -n <ns> -r <release> <chart-dir>

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

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

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

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

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

• Вышла 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.

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

• Предыдущий урок: M4.03 — Почему Helm 3 сменили на Nelm.
• Следующий урок: M4.05 — CLI Nelm целиком.
• Полная таблица аннотаций по стадиям: M7 урок 1.

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