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

#Обзор

Harbor Event Triggers позволяет автоматически запускать Tekton pipelines через Webhook-события Harbor. Он поддерживает несколько типов событий, включая отправку, получение, удаление артефактов и завершение сканирования, что позволяет построить полный 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. Подходит для:

• Автоматической сборки и развертывания образов
• Валидации и тестирования образов
• Автоматической маркировки и версионирования
• Многоэтапных 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 и значение по умолчанию не задано, trigger завершится с ошибкой разбора JSONPath.

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

spec:
  params:
    - name: artifact-tag
      default: ""  # Empty string default for optional field

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

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

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: при необходимости настройте заголовок аутентификации.
   • Skip Certificate Verification: включите, если используются self-signed certificates.
5. Выберите нужные типы событий:
   • Push Artifact: срабатывает при отправке артефактов
   • Pull Artifact: срабатывает при извлечении артефактов
   • Delete Artifact: срабатывает при удалении артефактов
   • Scanning Completed: срабатывает при завершении сканирования уязвимостей
6. Нажмите Save.

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

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

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

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

Далее нам нужно настроить только два приведенных ниже trigger:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
    name: my-pipeline-push   # It is suggested to modify the prefix based on the pipeline name
    namespace: my-namespace  # Change to actual namespace
spec:
    bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-push-artifact
    interceptors: # Filter to only process PUSH_ARTIFACT events
    - ref:
        kind: ClusterInterceptor
        name: cel
      params:
      - name: filter
        value: body.type == "PUSH_ARTIFACT"  # Only trigger on push events
    template:
      spec:
        params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # Optional field: may be empty if artifact is referenced by digest only
        - name: artifact-digest
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # It is suggested to modify the prefix based on the pipeline name
          spec:
              pipelineRef:
                name: my-pipeline  # Change to actual pipeline name
              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 need to be modified based on pipeline requirements and environment configuration
              - 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 # It is suggested to modify the prefix based on the pipeline name
  namespace: my-namespace # Change to actual namespace
spec:
  bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-scanning-completed
  interceptors: # Add Interceptor to filter successful scans only, or filter by vulnerability severity
  - ref:
      kind: ClusterInterceptor
      name: cel
    params:
    - name: filter
      value: |
        # Filter for successful scans only
        # Note: scan_overview structure varies by scan type, adjust the path accordingly
        # For vulnerability scans, the structure is: 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: ""  # Optional field: may be empty if artifact is referenced by digest only
        - name: artifact-digest
      resourcetemplates:
      - apiVersion: tekton.dev/v1
        kind: PipelineRun
        metadata:
          generateName: my-pipeline-scan- # It is suggested to modify the prefix based on the pipeline name
        spec:
          pipelineRef:
            name: my-pipeline # Modify based on the pipeline name
          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 need to be modified based on pipeline requirements and environment configuration
            - name: output
              emptyDir: {}

kubectl apply -f harbor-scanning-trigger.yaml

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

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

Сценарий: автоматически развертывать container images в staging или production environments, когда они отправляются в Harbor.

Настройка:

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

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

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

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

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

Настройка:

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

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

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

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

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

Настройка:

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

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

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

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

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

Настройка:

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

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

• Workflow сборка → тестирование → сканирование → развертывание
• Параллельное тестирование и сканирование для более быстрого получения обратной связи
• Условное развертывание на основе результатов тестов и сканирования