Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Когда стоит использовать шаг конвейера

Сущность FeatureRecipe даёт два способа сформировать вывод, который вносит сущность Feature: шаблонная FeatureRecipe, которая генерирует собственные документы, и шаг конвейера (pipeline:), который запускает Wasm-плагин над отрендеренным выводом. Они решают разные задачи. Эта страница — руководство по выбору: используйте шаг конвейера ровно в двух случаях, а во всех остальных — шаблонную FeatureRecipe.

Два инструмента

Шаблонная FeatureRecipe локальна и генеративна. Она создаёт собственные документы из собственных значений с помощью шаблона Go — ConfigMap для sidecar-контейнера, CRD политики, объект автомасштабирования. Всё, что она выдаёт, является функцией от values: и infra: сущности Feature и контекста рендеринга, передаваемого её шаблонам. Она никогда не обращается к выводу другой сущности; она добавляет собственные документы. Если то, что нужно создать, можно записать на основе того, что сущности Feature уже известно, шаблонная FeatureRecipe — правильный и более простой инструмент: без плагина и без конвейера.

Шаг конвейера глобален и преобразует. Он выполняется после рендеринга над реальным набором документов, который сборка уже выдала. Хост передаёт шагу этот набор документов с ключами целиком; шаг читает фактическое содержимое, выбирает целевые документы и возвращает точечные патчи RFC 6902 к их структуре — или выдаёт новые документы как побочные эффекты. Шаг рассуждает о том, что было отрендерено, а не только о том, что объявила сущность Feature. Этот охват — единственная причина его существования, и именно поэтому его следует применять умеренно.

Два случая для шага конвейера

Используйте шаг конвейера, только если выполняется одно из этих условий. Если ни одно не выполняется, генерируйте документ с помощью шаблонной FeatureRecipe.

  1. Патч в области хоста — нужно изменить структуру другой, уже отрендеренной сущности. Классический случай — внедрение переменной окружения, точки монтирования тома или sidecar-контейнера в рабочую нагрузку потребляющего компонента — документ, который сама сущность Feature не создавала. Шаблонная FeatureRecipe этого не может: она создаёт собственные документы и не редактирует чужие. Шаг конвейера может, потому что работает с отрендеренным набором и может обращаться к документам компонента-хоста по ключу.

  2. Выдача или патч, зависящие от содержимого, — вывод зависит от того, что содержит отрендеренный набор. Если выдаваемый ресурс или применяемый патч является функцией от содержимого, созданного сборкой, — фактических портов, объявленных в Deployment, имён контейнеров, оказавшихся в манифесте, ресурсов, в которые развернулся чарт, — для решения нужно иметь отрендеренное содержимое под рукой. Шаблонная FeatureRecipe рендерится из собственных значений сущности Feature и никогда не видит готовый набор, поэтому не может сделать выбор, зависящий от содержимого; шаг конвейера сначала читает содержимое, а затем действует.

У обоих случаев общая форма: им нужна информация, которая существует только после рендеринга, — структура другой сущности или само выданное содержимое. Локальной генерации это никогда не нужно, поэтому локальной генерации никогда не нужен шаг конвейера.

Шаг преобразует, политика проверяет

Шаг конвейера — это преобразователь: он изменяет отрендеренный набор. Это не место для проверки того, приемлем ли результат. Чтобы проверить сборку — убедиться, что в пропатченной рабочей нагрузке есть sidecar-контейнер, что ни один секрет в открытом виде не попал в вывод, что обязательная метка присутствует, — подключите политику этапа рендеринга: плагин управления в роли render-verdict, который выполняется после рендеринга над выданными артефактами и возвращает вердикт. Вердикт halt останавливает сборку; вердикт warn или info даёт рекомендацию, не блокируя её.

Разделяйте эти два инструмента. Не встраивайте логику проверки в шаг конвейера и не используйте политику для изменения вывода: плагин управления, подключённый в роли вердикта, возвращает вердикты и никогда не применяет патчи, а хост читает вывод роли вердикта только как решение. Шаг формирует вывод; политика render-verdict его оценивает. На странице сокета управления описаны все четыре роли управления и уровни серьёзности вердиктов.

Композиция шагов

Шаг конвейера может объявить типизированный контракт входа и выхода, так что его вход with: и возвращаемые выходы являются проверяемыми структурами, а не произвольными данными. Шаг также возвращает именованные outputs, и шаг, объявленный позже в том же конвейере, читает выходы предыдущего шага из своего шаблона with: как .steps.<id>.outputs.<key>. Так шаблон из двух частей компонуется без связывания: шаг Fetcher выдаёт ресурс учётных данных и публикует имя полученного Secret как выход; шаг Injector читает это имя и патчит потребляющую рабочую нагрузку, чтобы смонтировать его. Каждый шаг отвечает за одну задачу, а конвейер передаёт их выходы в объявленном порядке.

Перекрёстные ссылки

  • entities/featurerecipe.md — интерфейс создания FeatureRecipe, включая pipeline:.
  • plugins/plugin-contract.md — формат обмена шага конвейера: на входе набор документов с ключами, на выходе патчи RFC 6902, побочные эффекты, диагностика и выходы шага.
  • plugins/policy-socket.md — сокет управления, включая роль вердикта этапа рендеринга, которая проверяет вывод сборки.
  • templates/template-context-contract.md — поле .steps.<id>.outputs, которое читает более поздний шаг.
  • examples/04-secrets.md — вид конвейера Fetcher + Injector.