#TriggerTemplate

TriggerTemplate — это мощный компонент в Tekton Triggers, который определяет шаблон для ресурсов, которые должны быть созданы при обнаружении события. Он выступает в роли действия в event-driven pipeline, точно указывая, какие ресурсы Kubernetes (обычно TaskRuns или PipelineRuns) должны быть созданы в ответ на события.

#Объяснение терминологии

#Зачем нужен TriggerTemplate

#Проблема динамического создания ресурсов на основе событий

В CI/CD системах, реагирующих на внешние события, возникают следующие задачи при создании ресурсов:

1. Динамическое создание ресурсов: Ресурсы, такие как pipeline, должны создаваться с информацией, специфичной для каждого события.
2. Параметризация: Для разных событий необходимо передавать разные параметры в pipeline.
3. Повторное использование: Один и тот же шаблон создания ресурсов часто нужно использовать для разных событий.
4. Шаблонизация: Ручное создание ресурсов для каждого типа события подвержено ошибкам и не масштабируется.

Без TriggerTemplates решение этих задач потребовало бы:

• Пользовательских скриптов для генерации ресурсов Kubernetes для каждого события
• Сложной логики подстановки параметров
• Дублирования определений ресурсов в разных обработчиках событий
• Ручной синхронизации между данными события и созданием ресурсов

#Как TriggerTemplate решает эти задачи

TriggerTemplate предоставляет декларативный, нативный для Kubernetes способ:

1. Определять шаблоны ресурсов: Точно указывать, какие ресурсы создавать при возникновении событий.
2. Параметризовать ресурсы: Использовать параметры, извлечённые из событий, для настройки ресурсов.
3. Обеспечивать согласованность: Создавать ресурсы с одинаковой структурой для похожих событий.
4. Разделять обязанности: Разделять обнаружение событий (EventListener) и извлечение данных (TriggerBinding) от создания ресурсов.
5. Обеспечивать повторное использование: Определять шаблоны один раз и использовать их в нескольких триггерах.

Такой подход создаёт чистый декларативный способ определения действий при обнаружении событий, делая вашу CI/CD систему более поддерживаемой и масштабируемой.

#Преимущества

• Декларативное определение: Определение создаваемых ресурсов с помощью нативного YAML Kubernetes
• Параметризация: Динамическая настройка ресурсов с помощью данных событий
• Повторное использование: Создание шаблонов один раз и использование их в нескольких триггерах
• Разделение обязанностей: Чёткое разделение между обнаружением событий, извлечением данных и созданием ресурсов
• Значения по умолчанию: Возможность задавать запасные значения параметров, которые могут отсутствовать в событиях
• Динамическое именование: Генерация ресурсов с уникальными именами для предотвращения конфликтов
• Несколько ресурсов: Создание нескольких ресурсов из одного события
• Валидация ресурсов: Проверка ресурсов во время выполнения перед созданием

#Применимые сценарии

TriggerTemplates необходимы в следующих случаях:

1. Автоматизированные CI/CD пайплайны: Автоматическое создание pipeline run при пуше кода или открытии pull request.
2. Развёртывания в нескольких средах: Использование одного шаблона с разными параметрами для развёртывания в разных окружениях.
3. Event-driven workflows: Создание ресурсов в ответ на события внешних систем, например, обновления задач или оповещения мониторинга.
4. Динамическое создание ресурсов: Генерация ресурсов с параметрами, специфичными для каждого события, например, ID коммита или имя ветки.
5. Параметризованное тестирование: Создание тестовых pipeline с разными параметрами в зависимости от типа события.

#Ограничения и лимиты

• Параметры в TriggerTemplates могут быть только строковыми значениями
• JSON объекты требуют аккуратного обращения при использовании в параметрах
• Валидация ресурсов происходит во время выполнения, а не при создании
• Стандартные права сервисного аккаунта могут потребовать расширения для ресурсов вне Tekton
• Встроенные ресурсы должны быть включены в PipelineRun или TaskRun, которые их используют
• Имена параметров с числовыми префиксами требуют особой обработки

#Принципы

#Структура TriggerTemplate

TriggerTemplate состоит из двух основных разделов:

1. Определение параметров: Объявляет параметры, которые могут использоваться в шаблонах ресурсов
2. Шаблоны ресурсов: Определяет ресурсы Kubernetes, которые будут созданы

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: example-template
spec:
  params:
    - name: param1
      description: Описание параметра 1
      default: default-value  # Необязательное значение по умолчанию
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: example-pipeline-run-
      spec:
        pipelineRef:
          name: example-pipeline
        params:
          - name: pipeline-param
            value: $(tt.params.param1)

#Обработка параметров

Параметры в TriggerTemplates подчиняются следующим правилам:

1. Объявление: Параметры должны быть объявлены в разделе params с указанием имени и опционально описания и значения по умолчанию.
2. Ссылка: Параметры используются в шаблонах ресурсов с помощью синтаксиса $(tt.params.parameter-name).
3. Значения по умолчанию: Если параметр не передан через TriggerBinding, используется значение по умолчанию, если оно задано.
4. Строковые значения: Все значения параметров рассматриваются как строки, даже если они представляют числа или JSON объекты.
5. Специальные символы: Параметры с числовыми префиксами или специальными символами могут требовать кавычек в шаблонах ресурсов.

#Создание шаблонов ресурсов

При обнаружении и обработке события:

1. EventListener получает событие
2. Interceptors обрабатывают и фильтруют событие (если настроены)
3. TriggerBindings извлекают данные из события
4. TriggerTemplate получает извлечённые параметры
5. Выполняется подстановка параметров в шаблонах ресурсов
6. Создаются ресурсы Kubernetes с подставленными значениями

Каждому созданному ресурсу добавляются метки для отслеживания происхождения:

• tekton.dev/eventlistener: <EventListenerName>
• tekton.dev/triggers-eventid: <EventID>

#Примеры конфигураций

#Простой шаблон CI pipeline

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: ci-pipeline-template
spec:
  params:
    - name: git-revision
      description: SHA коммита git
    - name: git-repo-url
      description: URL репозитория git
    - name: git-repo-name
      description: Имя репозитория git
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: $(tt.params.git-repo-name)-ci-
      spec:
        pipelineRef:
          name: ci-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
          - name: repo-url
            value: $(tt.params.git-repo-url)
        workspaces:
          - name: source
            emptyDir: {}

#Шаблон для развёртывания в нескольких средах

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-template
spec:
  params:
    - name: environment
      description: Среда развёртывания
      default: development
    - name: image-tag
      description: Тег образа для развёртывания
    - name: app-name
      description: Имя приложения
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: deploy-$(tt.params.app-name)-$(tt.params.environment)-
      spec:
        pipelineRef:
          name: deployment-pipeline
        params:
          - name: target-environment
            value: $(tt.params.environment)
          - name: image-tag
            value: $(tt.params.image-tag)
          - name: application
            value: $(tt.params.app-name)

#Шаблон с несколькими ресурсами

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: multi-resource-template
spec:
  params:
    - name: git-revision
      description: SHA коммита git
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: build-pipeline-
      spec:
        pipelineRef:
          name: build-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: test-pipeline-
      spec:
        pipelineRef:
          name: test-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)

#Важные пояснения по параметрам, связанным с TriggerTemplate

#Подстановка параметров

Подстановка параметров — это основной механизм, делающий TriggerTemplates динамичными и переиспользуемыми.

#Применимые сценарии

• Вставка SHA коммитов в PipelineRuns
• Использование URL репозиториев и имён веток в параметрах pipeline
• Передача метаданных событий в pipeline
• Кастомизация имён ресурсов с учётом информации о событии

#Ограничения и лимиты

• Поддерживаются только строковые значения
• JSON объекты требуют специальной обработки
• Параметры с числовыми префиксами могут требовать кавычек

#Принципы/объяснение параметров

Синтаксис подстановки параметров: $(tt.params.parameter-name), где parameter-name — имя параметра, объявленного в разделе params TriggerTemplate.

Пример:

params:
  - name: git-revision
    description: SHA коммита git
resourcetemplates:
  - apiVersion: tekton.dev/v1beta1
    kind: PipelineRun
    spec:
      params:
        - name: revision
          value: $(tt.params.git-revision)

#Работа с JSON

При работе с JSON данными в TriggerTemplates требуются особые меры.

#Применимые сценарии

• Передача сложных структур данных в pipeline
• Работа с полезной нагрузкой webhook, содержащей вложенный JSON
• Создание ресурсов, требующих JSON конфигурации

#Ограничения и лимиты

• JSON объекты должны обрабатываться как строки
• Экранирование кавычек может быть сложным
• Для устаревших шаблонов могут потребоваться специальные аннотации

#Принципы/объяснение параметров

Для работы с JSON объектами:

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

   metadata:
     annotations:
       triggers.tekton.dev/old-escape-quotes: "true"

#Референсные материалы

• Tekton Triggers Documentation
• TriggerTemplate Official Documentation
• Tekton Pipelines Documentation
• Kubernetes Resource Management