#Interceptor

Interceptor — это мощный компонент в Tekton Triggers, который обрабатывает и фильтрует данные событий до того, как они попадут в TriggerBindings и TriggerTemplates. Он выступает в роли «привратника» и трансформатора входящих webhook-событий, позволяя проверять, фильтровать и изменять данные событий, чтобы только релевантные события запускали ваши пайплайны.

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

#Зачем нужны Interceptors

#Проблемы обработки событий

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

1. Валидация событий: Внешние webhook-и необходимо проверять, чтобы убедиться, что они поступают из доверенных источников.
2. Фильтрация событий: Не все события должны запускать пайплайны; требуется фильтрация по типам событий или содержимому.
3. Трансформация данных: Исходные payload-ы webhook часто содержат больше данных, чем нужно, или требуют переструктурирования.
4. Вопросы безопасности: Без надлежащей проверки webhook-эндпоинты могут быть уязвимы для злоупотреблений.

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

• Написания кастомного кода валидации для каждого источника webhook
• Сложной логики, встроенной в определения пайплайнов
• Ручной фильтрации и трансформации в скриптах
• Отдельных механизмов безопасности для каждой интеграции

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

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

1. Проверять события: Проверять подписи webhook и токены для подтверждения подлинности.
2. Фильтровать события: Обрабатывать только релевантные события по типу, содержимому или другим критериям.
3. Трансформировать данные: Извлекать, изменять или добавлять данные, делая их более подходящими для использования в пайплайнах.
4. Повышать безопасность: Внедрять единообразные практики безопасности для всех интеграций webhook.
5. Модульность логики: Разделять обработку событий и выполнение пайплайнов.

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

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

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

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

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

1. Безопасная обработка webhook: Когда нужно удостовериться, что события webhook поступают из доверенных источников.

2. Условный запуск пайплайнов: Когда требуется запускать пайплайны только для определённых типов событий или содержимого (например, только при push в основную ветку).

3. Обогащение данных: Когда нужно добавить вычисляемые значения или извлечь конкретные данные из сложных payload-ов событий.

4. Интеграция с несколькими источниками: При работе с несколькими провайдерами webhook (GitHub, GitLab, Bitbucket) с единообразной обработкой.

5. Кастомная обработка событий: При реализации специализированной логики обработки событий, выходящей за рамки стандартных interceptors.

#Ограничения и недостатки

• Interceptors добавляют накладные расходы на обработку событий
• Сложные выражения CEL могут быть трудны для отладки
• Кастомные interceptors требуют дополнительного развертывания и управления
• Рекомендуется использовать HTTPS для безопасности; поддержка HTTP будет удалена в будущих версиях
• Interceptors должны быть надёжно защищены для предотвращения несанкционированного доступа

#Принципы

#Архитектура Interceptor

Interceptors располагаются между EventListener и пайплайном обработки Trigger:

1. EventListener получает webhook-событие
2. Interceptors обрабатывают и фильтруют событие
3. TriggerBindings извлекают данные из обработанного события
4. TriggerTemplates создают ресурсы с использованием извлечённых данных

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

#Типы Interceptors

Tekton Triggers поддерживает два варианта реализации interceptors:

1. Отдельные Interceptors: реализованы как отдельные сервисы Kubernetes

   • Interceptor: ресурс с областью действия в пространстве имён
   • ClusterInterceptor: ресурс с областью действия на уровне кластера
   • Более гибкие и расширяемые
   • Могут быть реализованы на любом языке, способном обслуживать HTTP-запросы

2. Встроенные Interceptors: включены в pod EventListener

   • GitHub, GitLab, Bitbucket, CEL и др.
   • Сохраняются для обратной совместимости
   • Проще в использовании, но менее расширяемы

#Структура Interceptor

Базовый ресурс Interceptor имеет следующую структуру:

apiVersion: triggers.tekton.dev/v1alpha1
kind: Interceptor
metadata:
  name: my-interceptor
spec:
  clientConfig:
    service:
      name: my-interceptor-svc
      namespace: default
      path: "/optional-path"  # Опционально
      port: 8081  # По умолчанию 80

При ссылке в Trigger:

triggers:
  - name: trigger-with-interceptor
    interceptors:
      - ref:
          name: "my-interceptor"
          kind: Interceptor  # Или ClusterInterceptor
          namespace: default  # Обязательно только для Interceptor
        params:  # Опциональные параметры
          - name: "param1"
            value: "value1"

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

#Пример Interceptor для GitHub

triggers:
  - name: github-push-trigger
    interceptors:
      - ref:
          name: "github"
        params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["push"]
          - name: "branches"
            value: ["main", "release/*"]

#Пример Interceptor для GitLab с CEL

triggers:
  - name: gitlab-merge-request-trigger
    interceptors:
      - ref:
          name: "gitlab"
        params:
          - name: "secretRef"
            value:
              secretName: gitlab-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["Merge Request Hook"]
      - ref:
          name: "cel"
        params:
          - name: "filter"
            value: "body.object_attributes.state == 'opened' || body.object_attributes.state == 'reopened'"
          - name: "overlays"
            value:
              - key: truncated_sha
                expression: "body.object_attributes.last_commit.id.truncate(7)"

#Пример кастомного Interceptor

1. Создайте Deployment для вашего кастомного interceptor:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: custom-interceptor
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: custom-interceptor
     template:
       metadata:
         labels:
           app: custom-interceptor
       spec:
         containers:
           - name: custom-interceptor
             image: custom-interceptor:latest
             ports:
               - containerPort: 8080

2. Создайте Service для вашего кастомного interceptor:

   apiVersion: v1
   kind: Service
   metadata:
     name: custom-interceptor-svc
   spec:
     selector:
       app: custom-interceptor
     ports:
       - port: 80
         targetPort: 8080

3. Зарегистрируйте ваш кастомный interceptor:

   apiVersion: triggers.tekton.dev/v1alpha1
   kind: ClusterInterceptor
   metadata:
     name: custom-interceptor
   spec:
     clientConfig:
       service:
         name: custom-interceptor-svc
         namespace: default
         port: 80

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

#Выражения CEL

CEL (Common Expression Language) — мощный инструмент, используемый в interceptor CEL для фильтрации и трансформации данных событий.

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

• Фильтрация событий по сложным условиям
• Извлечение конкретных данных из payload-ов событий
• Создание новых полей на основе существующих данных
• Реализация условной логики

#Ограничения и недостатки

• Сложные выражения могут быть трудны для отладки
• Ограничены функциональностью CEL
• Возможное влияние на производительность при очень сложных выражениях

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

Распространённые шаблоны CEL:

• Доступ к полям body: body.repository.full_name
• Доступ к заголовкам: header.X-GitHub-Event
• Операции со строками: body.ref.split('/')[2]
• Условные выражения: body.action in ['opened', 'reopened', 'synchronize']
• Булева логика: body.pull_request.base.ref == 'main' && body.action == 'opened'

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

- ref:
    name: "cel"
  params:
    - name: "filter"
      value: "header.match('X-GitHub-Event', 'pull_request') && body.action in ['opened', 'reopened', 'synchronize']"
    - name: "overlays"
      value:
        - key: branch_name
          expression: "body.pull_request.head.ref"
        - key: is_main_target
          expression: "body.pull_request.base.ref == 'main'"

#Конфигурация HTTPS

Рекомендуется запускать interceptors по HTTPS для безопасности, и это будет обязательным в будущих версиях.

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

• Производственные среды
• Обработка чувствительных данных
• Соответствие требованиям безопасности

#Ограничения и недостатки

• Требуется правильное управление сертификатами
• Дополнительная конфигурация по сравнению с HTTP

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

Для настройки interceptor на HTTPS:

1. Добавьте метку server/type: https к вашему interceptor
2. Предоставьте CA bundle для проверки сертификатов
3. Убедитесь, что сервис interceptor настроен на работу по HTTPS

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

apiVersion: triggers.tekton.dev/v1alpha1
kind: Interceptor
metadata:
  name: secure-interceptor
  labels:
    server/type: https
spec:
  clientConfig:
    caBundle: "BASE64_ENCODED_CA_BUNDLE"
    service:
      name: secure-interceptor-svc
      namespace: default
      port: 8443

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

• Tekton Triggers Interceptors Documentation
• Namespaced Interceptors Documentation
• Cluster Interceptors Documentation
• CEL Language Specification
• Implementing Custom Interceptors