#TriggerBinding

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

#Пояснение терминологии

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

#Проблема с пайплайнами, ориентированными на события

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

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

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

#Как TriggerBinding решает эти проблемы

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

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

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

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

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

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

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

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

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

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

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: Создан в качестве отдельного ресурса для повторного использования в нескольких триггерах.

   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

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
• Официальная документация TriggerBinding
• Документация TriggerTemplate
• Документация EventListener