#Использование триггеров событий Harbor

#Overview

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

#Core Features

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

#Supported Event Types

#Basic Event Information

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

#Basic Variables (Общие для всех событий)

#1. Push Artifact Event

Срабатывает при push артефакта (контейнерного образа или OCI chart) в репозиторий Harbor. Подходит для:

• Автоматической сборки и деплоя образов
• Валидации и тестирования образов
• Автоматического тегирования и версионирования
• Многоступенчатых build pipeline

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

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

#2. Pull Artifact Event

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

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

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

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

#3. Delete Artifact Event

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

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

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

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

#4. Scanning Completed Event

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

• Применения политик безопасности
• Автоматических проверок безопасности
• Отчётности по уязвимостям
• Автоматизации процессов исправления

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

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

#Configuration Guide

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

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

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

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

• Автоматический запуск сборки и деплоя при push образа
• Автоматический запуск проверок безопасности при завершении сканирования

Для упрощения документации предполагается, что 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: # Рабочие пространства нужно изменить в соответствии с требованиями 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: # Рабочие пространства нужно изменить в соответствии с требованиями pipeline и конфигурацией среды
            - name: output
              emptyDir: {}

kubectl apply -f harbor-scanning-trigger.yaml

#Use Cases

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

Сценарий: Автоматически деплоить контейнерные образы в staging или production при их push в Harbor.

Настройка:

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

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

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

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

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

Настройка:

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

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

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

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

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

Настройка:

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

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

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

#Сценарий 4: Многоступенчатый CI/CD pipeline

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

Настройка:

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

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

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