#TriggerBinding

TriggerBinding — ключевой компонент в Tekton Triggers, который позволяет извлекать поля из полезной нагрузки события и связывать их с именованными параметрами. Эти параметры затем могут использоваться в TriggerTemplate для создания ресурсов, таких как TaskRuns и PipelineRuns, с конкретными значениями, извлечёнными из события.

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

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

#Проблема событийно-ориентированных конвейеров

В CI/CD процессах внешние системы (например, GitHub, GitLab или другие провайдеры webhook) отправляют события с определёнными структурами данных. Эти события содержат ценную информацию, такую как идентификаторы коммитов, URL репозиториев, имена веток и другую метадату, которая должна использоваться при выполнении конвейера.

Без TriggerBindings не было бы стандартизированного способа:

• Извлекать конкретные поля из сложных полезных нагрузок событий
• Преобразовывать эти данные в параметры, которые могут использоваться конвейерами
• Обрабатывать различные структуры событий от разных систем

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

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

1. Извлекать конкретные поля из полезных нагрузок событий с помощью выражений JSONPath
2. Преобразовывать эти поля в именованные параметры, к которым можно обращаться в TriggerTemplates
3. Разделять ответственность между извлечением данных и созданием ресурсов

Это разделение позволяет командам создавать повторно используемые биндинги, которые можно комбинировать с разными шаблонами, делая процесс от события к конвейеру более модульным и удобным для поддержки.

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

• Повторное использование: Создавайте биндинги один раз и используйте их в нескольких триггерах
• Гибкость: Извлекайте данные как из HTTP-заголовков, так и из JSON-тела
• Варианты области действия: Используйте TriggerBindings на уровне namespace или ClusterTriggerBindings на уровне всего кластера
• Механизм резервного значения: Если поле не найдено, система может использовать значения по умолчанию из TriggerTemplate
• Композиция: Несколько биндингов можно комбинировать в одном Trigger для извлечения разных наборов данных

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

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

1. Автоматизация CI/CD конвейеров: Автоматический запуск конвейеров при пуше кода в репозиторий с извлечением деталей коммита для использования в конвейере.

2. Многоокружные деплои: Использование одних и тех же данных события в сочетании с биндингами, специфичными для окружения, для деплоя в разные среды.

3. Обработка кастомных webhook: Извлечение релевантных данных из кастомных webhook для запуска соответствующих конвейеров с нужными параметрами.

4. Обработка сложных событий: При работе со сложными структурами событий, когда для выполнения конвейера нужны только определённые вложенные поля.

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

• TriggerBindings могут извлекать только те данные, которые присутствуют в полезной нагрузке события
• Выражения JSONPath должны быть корректно отформатированы и обёрнуты в синтаксис $()
• Имена полей в HTTP-заголовках чувствительны к регистру
• Специальные символы в ключах JSON (например, точки или слэши) должны экранироваться обратными слэшами

#Принципы

#Структура и типы TriggerBinding

Существует три способа объявления TriggerBinding:

1. Встроенные биндинги: Определяются непосредственно внутри ресурса Trigger

   apiVersion: triggers.tekton.dev/v1beta1
   kind: Trigger
   metadata:
     name: push-trigger
   spec:
     bindings:
     - name: gitrevision
       value: $(body.head_commit.id)
     - name: gitrepositoryurl
       value: $(body.repository.url)
     template:
       ref: git-clone-template

2. Ресурс TriggerBinding: Создаётся как отдельный ресурс для повторного использования в нескольких Trigger

   apiVersion: triggers.tekton.dev/v1beta1
   kind: TriggerBinding
   metadata:
     name: pipeline-binding
   spec:
     params:
     - name: gitrevision
       value: $(body.head_commit.id)
     - name: gitrepositoryurl
       value: $(body.repository.url)
     - name: contenttype
       value: $(header.Content-Type)

3. ClusterTriggerBinding: Биндинг с областью действия на уровне кластера для повторного использования во всём кластере

   apiVersion: triggers.tekton.dev/v1beta1
   kind: ClusterTriggerBinding
   metadata:
     name: pipeline-clusterbinding
   spec:
     params:
       - name: gitrevision
         value: $(body.head_commit.id)
       - name: gitrepositoryurl
         value: $(body.repository.url)
       - name: contenttype
         value: $(header.Content-Type)

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

TriggerBindings используют выражения JSONPath, обёрнутые в синтаксис $(), для доступа к данным:

• Доступ к телу HTTP: $(body.repository.url)
• Доступ к HTTP-заголовкам: $(header.Content-Type)
• Доступ к данным интерцептора: $(extensions.field-name)
• Доступ к контексту EventListener: $(context.eventID)
• Обработка специальных символов: $(body.dev\.tekton\.dev\/foo)

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

#Простой TriggerBinding для GitHub webhook

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: github-push-binding
spec:
  params:
  - name: gitrevision
    value: $(body.after)
  - name: gitrepositoryurl
    value: $(body.repository.clone_url)
  - name: gitrepositoryname
    value: $(body.repository.name)
  - name: gitusername
    value: $(body.pusher.name)

#Пример с несколькими биндингами

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: listener
spec:
  triggers:
    - name: prod-trigger
      bindings:
        - ref: event-binding
        - ref: prod-env
      template:
        ref: pipeline-template
    - name: staging-trigger
      bindings:
        - ref: event-binding
        - ref: staging-env
      template:
        ref: pipeline-template

#Важные пояснения по параметрам

#Выражения JSONPath

Выражения JSONPath — основной механизм извлечения данных в TriggerBindings.

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

• Извлечение вложенных полей из сложных JSON-структур
• Доступ к элементам массивов в полезной нагрузке
• Доступ к всему телу или заголовкам

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

• Должны быть обёрнуты в синтаксис $()
• Вложенные обёртки $() интерпретируются как внутреннее выражение
• Некорректные выражения приводят к пустым значениям

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

Распространённые паттерны JSONPath:

$(body) -> заменяется на всё тело
$(body.key1) -> значение ключа key1 в теле
$(body.key2.key3) -> доступ к вложенному значению
$(body.key4[0]) -> первый элемент массива
$(header.Content-Type) -> значение заголовка Content-Type

#Справочные материалы

• Tekton Triggers Documentation
• TriggerBinding Official Documentation
• TriggerTemplate Documentation
• EventListener Documentation