#Использование Harbor Event Triggers

#Обзор

Harbor Event Triggers позволяет автоматически запускать Tekton pipelines через Webhook-события Harbor. Поддерживаются несколько типов событий, включая push, pull, delete артефактов и завершение сканирования, что позволяет построить полный workflow автоматизации CI/CD для container images и OCI charts.

#Ключевые возможности

• Поддержка нескольких типов событий: Поддерживает различные события Harbor, такие как Push Artifact, Pull Artifact, Delete Artifact и Scanning Completed.
• Стандартизированная привязка триггеров: Предоставляет стандартизированные ClusterTriggerBindings для обеспечения согласованности между платформами.
• Гибкое сопоставление параметров: Автоматически извлекает ключевую информацию из событий Harbor для параметров pipeline.
• Поддержка нескольких типов артефактов: Поддерживает как container images, так и OCI charts.

#Поддерживаемые типы событий

#Базовая информация о событии

Все выходные переменные можно использовать для сопоставления параметров pipeline. Вы можете получать значения параметров с помощью $(tt.params.<param name>).

#Базовые переменные (общие для всех событий)

#1. Событие Push Artifact

Срабатывает, когда артефакт (container image или OCI chart) загружается в репозиторий Harbor. Подходит для:

• Автоматической сборки и развертывания images
• Проверки и тестирования images
• Автоматического тегирования и версионирования
• Многоэтапных pipeline сборки

#Переменные события Push Artifact

Также доступны все базовые переменные, перечисленные выше.

#2. Событие Pull Artifact

Срабатывает, когда артефакт извлекается из репозитория Harbor. Подходит для:

• Отслеживания использования и аналитики
• Мониторинга безопасности
• Отслеживания потребления ресурсов
• Проверки развертываний

#Переменные события Pull Artifact

Также доступны все базовые переменные, перечисленные выше.

#3. Событие Delete Artifact

Срабатывает, когда артефакт удаляется из репозитория Harbor. Подходит для:

• Автоматизации очистки
• Аудитного журналирования
• Управления ресурсами
• Отслеживания соответствия требованиям

#Переменные события Delete Artifact

Доступны все базовые переменные, перечисленные выше. Обратите внимание, что repository-date-created недоступно для событий delete.

#4. Событие Scanning Completed

Срабатывает, когда завершается сканирование уязвимостей артефакта. Подходит для:

• Применения политик безопасности
• Автоматизированных проверок безопасности
• Формирования отчетов об уязвимостях
• Автоматизированных workflow устранения проблем

#Переменные события Scanning Completed

Доступны все базовые переменные, перечисленные выше. Обратите внимание, что repository-date-created недоступно для событий scanning.

#Руководство по настройке

#Обработка необязательных полей

Некоторые поля в событиях Harbor могут быть необязательными или отсутствовать в зависимости от типа события или способа указания артефакта. Например:

• artifact-tag: Может отсутствовать, если артефакт указан только по digest
• repository-date-created: Доступно в событиях push и pull, но не в событиях delete и scanning

Важно: При использовании ClusterTriggerBindings, которые ссылаются на необязательные поля, вы обязаны указать значения по умолчанию в вашем TriggerTemplate для этих параметров. Если поле отсутствует в payload и значение по умолчанию не задано, триггер завершится ошибкой разбора JSONPath.

Пример: Чтобы обработать необязательное поле artifact-tag, настройте ваш TriggerTemplate следующим образом:

spec:
  params:
    - name: artifact-tag
      default: ""  # Значение по умолчанию в виде пустой строки для необязательного поля

Это гарантирует, что если поле tag отсутствует в payload события Harbor, триггер использует пустую строку вместо ошибки.

#Предварительные требования

1. В окружении создан EventListener, который способен обрабатывать Trigger в целевом namespace. Для получения дополнительной информации обратитесь к администратору платформы.
2. Harbor может получить доступ к указанному выше EventListener.
3. Необходимый Pipeline, а также требуемые конфигурации выполнения, уже созданы.
4. У вас есть права на изменение настроек Webhook проекта Harbor.

#Настройка Webhook через UI Harbor

1. Откройте настройки вашего проекта Harbor.
2. Перейдите в раздел Webhooks.
3. Нажмите New Webhook.
4. Настройте webhook:
   • Name: Укажите понятное имя (например, tekton-webhook)
   • Endpoint URL: Укажите URL EventListener, например:

     http://<your-eventlistener-url>
     или

     https://<your-eventlistener-url>
   • Auth Header: (Optional) Настройте заголовок аутентификации, если это требуется.
   • Skip Certificate Verification: Включите, если используются самоподписанные сертификаты.
5. Выберите нужные типы событий:
   • Push Artifact: Срабатывает при загрузке артефактов
   • Pull Artifact: Срабатывает при извлечении артефактов
   • Delete Artifact: Срабатывает при удалении артефактов
   • Scanning Completed: Срабатывает при завершении сканирования уязвимостей
6. Нажмите Save.

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

Если цель — реализовать непрерывную интеграцию через триггер со следующими требованиями:

• Автоматически запускать сборку и развертывание при загрузке image.
• Автоматически запускать проверки безопасности при завершении сканирования.

Чтобы упростить эту документацию, предположим, что pipeline уже подготовлен со следующими параметрами:

Далее нам нужно настроить только два триггера ниже:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
    name: my-pipeline-push   # Рекомендуется изменить префикс в зависимости от имени pipeline
    namespace: my-namespace  # Измените на фактический namespace
spec:
    bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-push-artifact
    interceptors: # Фильтрация только для обработки событий PUSH_ARTIFACT
    - ref:
        kind: ClusterInterceptor
        name: cel
      params:
      - name: filter
        value: body.type == "PUSH_ARTIFACT"  # Запускать только при событиях push
    template:
      spec:
        params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # Необязательное поле: может быть пустым, если артефакт указан только по digest
        - name: artifact-digest
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # Рекомендуется изменить префикс в зависимости от имени pipeline
          spec:
              pipelineRef:
                name: my-pipeline  # Измените на фактическое имя pipeline
              params:
              - name: repository-full-name
                value: $(tt.params.repository-full-name)
              - name: artifact-tag
                value: $(tt.params.artifact-tag)
              - name: artifact-digest
                value: $(tt.params.artifact-digest)
              workspaces: # Workspaces необходимо изменить в соответствии с требованиями pipeline и конфигурацией окружения
              - name: output
                emptyDir: {}

kubectl apply -f harbor-push-trigger.yaml

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PUSH_ARTIFACT"

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PULL_ARTIFACT"

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: my-pipeline-scanning # Рекомендуется изменить префикс в зависимости от имени pipeline
  namespace: my-namespace # Измените на фактический namespace
spec:
  bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-scanning-completed
  interceptors: # Добавьте Interceptor для фильтрации только успешных сканирований или по уровню критичности уязвимостей
  - ref:
      kind: ClusterInterceptor
      name: cel
    params:
    - name: filter
      value: |
        # Фильтр только для успешных сканирований
        # Примечание: структура scan_overview зависит от типа сканирования, при необходимости скорректируйте путь
        # Для сканирований уязвимостей структура выглядит так: body.event_data.resources[0].scan_overview["application/vnd.security.vulnerability.report; version=1.1"].scan_status == "Success"
  template:
    spec:
      params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # Необязательное поле: может быть пустым, если артефакт указан только по digest
        - name: artifact-digest
      resourcetemplates:
      - apiVersion: tekton.dev/v1
        kind: PipelineRun
        metadata:
          generateName: my-pipeline-scan- # Рекомендуется изменить префикс в зависимости от имени pipeline
        spec:
          pipelineRef:
            name: my-pipeline # Измените в соответствии с именем pipeline
          params:
            - name: repository-full-name
              value: $(tt.params.repository-full-name)
            - name: artifact-tag
              value: $(tt.params.artifact-tag)
            - name: artifact-digest
              value: $(tt.params.artifact-digest)
          workspaces: # Workspaces необходимо изменить в соответствии с требованиями pipeline и конфигурацией окружения
            - name: output
              emptyDir: {}

kubectl apply -f harbor-scanning-trigger.yaml

#Сценарии использования

#Сценарий использования 1: Автоматическое развертывание images

Сценарий: Автоматически развертывать container images в staging или production окружения при их загрузке в Harbor.

Конфигурация:

• Создать Trigger с использованием binding harbor-push-artifact
• Настроить pipeline на получение image через artifact-resource-url и развертывание его в целевом окружении
• При необходимости фильтровать по namespace репозитория или шаблону тега с помощью CEL interceptors

Примеры использования:

• Развертывание images с тегом production в production окружение
• Развертывание images из определенных namespaces в staging окружение
• Запуск развертывания только для images, соответствующих определенным шаблонам именования

#Сценарий использования 2: Применение политик безопасности

Сценарий: Применять политики безопасности, блокируя развертывание images с критическими уязвимостями.

Конфигурация:

• Создать Trigger с использованием binding harbor-scanning-completed
• Использовать CEL interceptor для фильтрации сканирований с критическими уязвимостями
• Настроить pipeline, чтобы:
  • Проверять количество уязвимостей по результатам сканирования
  • Блокировать развертывание, если количество критических уязвимостей превышает порог
  • Отправлять уведомления команде безопасности

Примеры использования:

• Запрещать развертывание images с критическими уязвимостями
• Автоматически помещать в карантин images с уязвимостями высокого риска
• Генерировать отчеты по безопасности для целей соответствия требованиям

#Сценарий использования 3: Управление жизненным циклом артефактов

Сценарий: Автоматически управлять жизненным циклом артефактов на основе шаблонов использования и политик хранения.

Конфигурация:

• Создать Triggers для событий harbor-pull-artifact и harbor-delete-artifact
• Отслеживать использование и возраст артефактов
• Автоматически удалять старые или неиспользуемые артефакты на основе политик

Примеры использования:

• Архивировать старые артефакты, которые не извлекались в течение 90 дней
• Очищать артефакты разработки после развертывания в production
• Обеспечивать соответствие политикам хранения данных

#Сценарий использования 4: Многоэтапный CI/CD pipeline

Сценарий: Построить полный CI/CD pipeline, который запускается при загрузке image, выполняет тесты, проводит сканирование безопасности и выполняет развертывание на основе результатов сканирования.

Конфигурация:

• Создать несколько Triggers:
  1. Trigger harbor-push-artifact: запуск pipeline сборки и тестирования
  2. Trigger harbor-scanning-completed: продолжение развертывания, если сканирование прошло успешно
• Использовать зависимости pipeline и workspaces для обмена артефактами между этапами

Примеры использования:

• Workflow Build → Test → Scan → Deploy
• Параллельное тестирование и сканирование для более быстрой обратной связи
• Условное развертывание на основе результатов тестов и сканирования