Быстрый старт
Это руководство поможет вам начать работу с Tekton Triggers, создав простой сценарий триггера "Hello World" для демонстрации его базовой функциональности. Руководство включает следующие шаги:
- Настроить правила автоматического экспонирования
EventListenerдля внешнего доступа - Создать
EventListenerи связанные ресурсы - Получить автоматически сгенерированный адрес webhook из статуса
EventListener
Содержание
Предварительные требованияШаг 1: Настройка правил автоматического экспонирования EventListenerПредварительные требованияШаг 2: Создание примерного проектаШаг 3: Создание Hello World TaskRunАльтернатива: Простой тестовый запускВариант A: Использование Port-Forward (Самый простой)Вариант B: Использование NodePortШаг 4: Получение адреса вебхука и тестирование (с использованием автоматического экспонирования)Следующие шагиЧасто задаваемые вопросыПредварительные требования
-
Требования к окружению
Kubernetesверсии 1.21 или выше- Установлен
Tekton Operator - Убедитесь, что
Tekton Triggersустановлен и готов к работе через Operator
-
Необходимые инструменты
- Командная строка
kubectl curl(для тестирования триггеров)
- Командная строка
-
Права доступа
- Требуются привилегии администратора кластера (для настройки правил автоматического экспонирования
EventListener) - Требуются привилегии администратора пространства имён (для создания ресурсов
EventListener)
- Требуются привилегии администратора кластера (для настройки правил автоматического экспонирования
Шаг 1: Настройка правил автоматического экспонирования EventListener
О функции автоматического экспонирования
Это улучшение платформы Alauda (не входит в стандартный Tekton Triggers), которое упрощает настройку внешнего доступа к EventListener.
Три способа экспонирования EventListener:
-
Автоматическое экспонирование (улучшение Alauda) ⭐ Рекомендуется для продакшена
- Автоматически создаёт и управляет ресурсами
Ingress - Централизованная настройка через
TektonConfig - URL вебхуков автоматически заполняются в статусе
EventListener - Лучший вариант для продакшен-сред с несколькими
EventListener
- Автоматически создаёт и управляет ресурсами
-
Ручное создание Ingress (стандартный подход Tekton)
- Вы вручную создаёте ресурсы
Ingressдля каждогоEventListener - Больше контроля, но требует больше поддержки
- Стандартный подход Kubernetes
- Вы вручную создаёте ресурсы
-
Port-Forward или NodePort (тестирование/разработка) 🚀 Самый простой старт
- Не требуется настройка
Ingressили DNS - Отлично подходит для локального тестирования и обучения
- См. раздел Простой тестовый запуск, если хотите быстро начать
- Не требуется настройка
Если вы новичок в Triggers, можете пропустить этот шаг и перейти к разделу Простой тестовый запуск, чтобы начать с port-forward. Вернитесь к настройке автоматического экспонирования позже, когда будете готовы к продакшен-развёртыванию.
Функция автоматического экспонирования EventListener автоматически создаёт ресурсы Ingress для ваших EventListener на основе настроенных правил экспорта. Это избавляет от необходимости вручную создавать и управлять ресурсами Ingress. Сначала необходимо настроить эти правила, чтобы EventListener были доступны по внешним URL. Подробные инструкции по настройке смотрите в разделе Настройка правил автоматического экспонирования EventListener.
Предварительные требования
Перед настройкой правил экспорта убедитесь, что у вас есть следующие условия:
-
Конфигурация LoadBalancer или Gateway (рекомендуется для продакшена):
- Для продакшен-сред рекомендуется использовать
LoadBalancerилиGatewayдля экспонированияEventListener LoadBalancer/Gatewayдолжен быть настроен и доступен- У вас должен быть внешний домен или IP-адрес, который будет использоваться для вебхуков
- Для продакшен-сред рекомендуется использовать
-
Ingress Controller (если используется Ingress):
- В вашем кластере должен быть установлен и запущен контроллер
Ingress(например,NGINX,ALBилиTraefik) - Вы должны знать имя
IngressClass, который будет использоваться - Подробнее о создании Ingress смотрите в Creating Ingresses.
- В вашем кластере должен быть установлен и запущен контроллер
-
Домен и сертификат (для HTTPS):
- Если используете HTTPS, убедитесь, что у вас настроено доменное имя
- TLS-сертификаты должны быть подготовлены (созданы вручную или через
cert-manager)
Важные замечания:
- Функция автоматического экспонирования автоматически создаст ресурсы
Ingressна основе правил экспорта. Обычно не нужно создавать или изменятьIngressвручную. - Если вы используете
LoadBalancerс нестандартным портом, убедитесь, что порт указан в полеexternalHosts(например,https://webhooks.example.com:8443). - Для разработки или тестирования можно использовать
NodePortвместоIngress/LoadBalancer. Подробнее смотрите в пример настройки NodePort.
Настройка правил экспорта через TektonConfig
Создайте или обновите ресурс TektonConfig, чтобы настроить правила экспорта. Создайте файл tektonconfig.yaml:
Принцип работы автоматического экспонирования
Функция автоматического экспонирования работает следующим образом:
- Считывает правила экспорта, которые вы настроили в
TektonConfig - Автоматически создаёт ресурсы
IngressдляEventListener, соответствующих правилам - Заполняет поле
status.addressesуEventListenerURL вебхуков, которые можно отображать в UI - Исключает необходимость вручную создавать и управлять ресурсами
Ingressдля каждогоEventListener
Такой подход обеспечивает централизованное управление способом экспонирования EventListener, упрощая поддержку единых шаблонов URL вебхуков в кластере.
Выбор метода конфигурации Ingress
Функция автоматического экспонирования поддерживает два метода настройки Ingress для внешнего доступа к EventListener. Выберите подходящий для вашего окружения:
Альтернатива: настройка NodePort
Если у вас нет LoadBalancer или контроллера Ingress, либо вы предпочитаете более простую настройку для разработки/тестирования, можно использовать NodePort. Подробнее смотрите в пример настройки NodePort. При использовании NodePort функция автоматического экспонирования не требуется, так как доступ к EventListener осуществляется напрямую по IP узла и порту NodePort.
Метод 1: Общая настройка Ingress (рекомендуется для продакшена)
Этот метод подходит для большинства Kubernetes-сред. Необходимо:
-
Создать IngressClass (если ещё не создан): подробности смотрите в Creating Ingresses.
-
Или использовать сервис LoadBalancer для получения внешнего IP-адреса подробности смотрите в Configure a Load Balancer.
-
Настроить правила экспорта в зависимости от вашей конфигурации Ingress:
- Если используете IngressClass: укажите
ingressClassс именем вашего IngressClass (например,nginx) - Если используете LoadBalancer: получите внешний IP/домен из сервиса LoadBalancer и настройте поля
hostиexternalHostsсоответственно
- Если используете IngressClass: укажите
Пример конфигурации для IngressClass:
Настройка DNS: При указании домена в поле host убедитесь, что:
- DNS-записи корректно настроены и домен разрешается в IP адрес контроллера Ingress
- Для локального тестирования можно добавить домен в
/etc/hosts(Linux/Mac) илиC:\Windows\System32\drivers\etc\hosts(Windows) - Домен должен быть доступен с систем, которые будут отправлять вебхуки (GitHub, GitLab и др.)
Метод 2: Быстрый старт для бизнес-кластеров ACP
Если вы используете бизнес-кластер ACP (Alauda Container Platform), можно воспользоваться встроенным шлюзом платформы для быстрой настройки:
- Получите адрес доступа к платформе ACP (например,
https://192.168.1.100) - Получите имя вашего кластера (например,
test) - Настройте правила экспорта следующим образом:
- Установите
hostв пустое значение (или используйте подстановочный знак*) - Укажите
externalHostsкак:<Адрес доступа к платформе ACP>/clusters-rewrite/<Имя кластера> - Итоговый URL вебхука будет:
<externalHost>/<urlPathPrefix>/<namespace-eventlistener>/<имя-eventlistener>
- Установите
Пример конфигурации для ACP:
С такой конфигурацией адрес вебхука будет:
Формула настройки ACP:
- URL платформы ACP:
https://192.168.1.100 - Имя кластера:
test - Префикс пути URL:
/triggers(настраиваемый) - Внешний хост:
https://192.168.1.100/clusters-rewrite/test - Итоговый URL вебхука:
https://192.168.1.100/clusters-rewrite/test/triggers/<namespace-eventlistener>/<имя-eventlistener>
Пример: Если адрес платформы ACP https://192.168.1.100, имя кластера test, а urlPathPrefix — /triggers, то адрес доступа будет https://192.168.1.100/clusters-rewrite/test/triggers.
Важно: Замените значения-заполнители (webhooks.example.com, nginx и т.д.) на ваши реальные доменное имя, класс ingress и URL внешнего хоста. Если у вас нет настроенного домена, можно использовать пустое поле host и указать в externalHosts ваш реальный доступный URL.
Применение TektonConfig
Проверка конфигурации
Подождите несколько секунд, пока Operator синхронизирует конфигурацию, затем проверьте:
В ConfigMap должна содержаться ваша конфигурация правил экспорта. (Примечание: имя ConfigMap — trigger-wrapper-config — это внутреннее техническое имя; запоминать его не нужно, так как управление конфигурацией происходит через TektonConfig.)
Шаг 2: Создание примерного проекта
Создание пространства имён
О ServiceAccount для EventListener
Для этого быстрого старта мы используем стандартный ServiceAccount, который автоматически создаётся системой Tekton Triggers. Этот ServiceAccount называется triggers-default-sa и имеет права в пределах пространства имён.
Как это работает:
- При установке
Tekton Triggersавтоматически создаётся стандартныйServiceAccountв каждом пространстве имён - Найти его можно командой:
kubectl get sa -n tekton-triggers-demo -l triggers.tekton.dev/default-service-account - Этот
ServiceAccountимеет права на созданиеTaskRunsиPipelineRunsв пределах того же пространства имён - Ручная настройка не требуется — просто указывайте его имя:
triggers-default-sa
Когда нужен кастомный ServiceAccount:
- Если нужно создавать ресурсы в нескольких пространствах имён (триггеры с кросс-пространственным доступом)
- Если требуются дополнительные права сверх стандартных
- Смотрите раздел Настройка EventListener для настройки кастомного
ServiceAccount
Шаг 3: Создание Hello World TaskRun
Создание задачи
Создайте файл hello-task.yaml:
Создание Trigger Template
Создайте файл trigger-template.yaml:
Создание Trigger Binding
Создайте файл trigger-binding.yaml:
Создание Event Listener
Создайте файл event-listener.yaml:
Примечание по ServiceAccount: Мы используем автоматически созданный стандартный ServiceAccount (указан serviceAccountName: triggers-default-sa). Этот ServiceAccount создаётся системой Tekton Triggers и имеет права на создание TaskRuns/PipelineRuns в пределах того же пространства имён. Этого достаточно для данного примера, так как все ресурсы находятся в одном пространстве имён. Функция автоматического экспонирования автоматически создаст Ingress для этого EventListener на основе правил экспорта, настроенных на шаге 1.
Применение конфигурации
Примените все созданные ресурсы:
Альтернатива: Простой тестовый запуск
Если вы пропустили Шаг 1 (настройку автоматического экспонирования) и хотите быстро протестировать, можно использовать port-forward или NodePort для доступа к EventListener без настройки Ingress или DNS.
Вариант A: Использование Port-Forward (Самый простой)
Ожидание готовности EventListener
Проброс локального порта к EventListener
Оставьте этот терминал открытым. Теперь EventListener доступен по адресу http://localhost:8080.
Отправка тестового запроса через port-forward
Откройте новый терминал и выполните:
Просмотр результатов
Вариант B: Использование NodePort
Для доступа к EventListener с других машин без Ingress:
Патчинг сервиса EventListener на NodePort
Получение NodePort
Отправка тестового запроса через NodePort
Когда использовать каждый метод:
- Port-forward: локальное тестирование, разработка, обучение
- NodePort: тестирование с других машин, кластеры для разработки
- Автоматическое экспонирование (Ingress): продакшен-развёртывания, внешние вебхуки (GitHub, GitLab и др.)
Шаг 4: Получение адреса вебхука и тестирование (с использованием автоматического экспонирования)
Ожидание готовности EventListener
Получение автоматически сгенерированного адреса вебхука
Функция автоматического экспонирования автоматически генерирует внешние адреса вебхуков на основе правил экспорта, настроенных на Шаге 1. Эти адреса заполняются в поле status.addresses у EventListener:
Формат адреса: Адрес вебхука имеет шаблон: <externalHost>/<urlPathPrefix>/<namespace-eventlistener>/<имя-eventlistener>
Например: https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener
Если status.addresses пуст, проверьте:
- Совпадают ли настроенные правила экспорта с пространством имён вашего
EventListener - Запущен ли контроллер автоматического экспонирования и обработал ли он
EventListener - Просмотрите логи контроллера:
kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
Доступность сети: Убедитесь, что ваш внешний URL доступен с места, где вы тестируете. Если тестируете внутри кластера, возможно, потребуется использовать port-forward или обращаться к внутреннему адресу сервиса.
Проверка доступности домена вебхука
Перед отправкой тестовых запросов проверьте доступность домена вебхука:
Важно: Убедитесь, что домен вебхука на базе LoadBalancer/Gateway доступен из внешних систем. Если вы настраиваете вебхуки в GitHub, GitLab или других внешних системах, они должны иметь возможность достучаться до этого URL. Проверьте:
- Корректность DNS-записей
- Правильность настройки и доступность LoadBalancer/Gateway
- Правила файрвола, разрешающие входящий трафик
- Валидность TLS-сертификатов (если используется HTTPS)
Отправка тестового запроса на вебхук
Просмотр результатов
Очистка ресурсов
После тестирования можно удалить созданные ресурсы:
Следующие шаги
Теперь, когда вы успешно создали и протестировали базовый пример Tekton Triggers, вы можете:
- Изучить концепции Tekton Triggers
- Узнать, как использовать Настройку EventListener для типовых инструкций
- Настроить правила автоматического экспонирования EventListener для продвинутых сценариев
- Настроить и использовать события Gitlab для запуска pipeline
Часто задаваемые вопросы
-
Pod EventListener не запускается
- Проверьте, достаточно ли прав у стандартного
ServiceAccountв пространстве имён - Убедитесь, что ресурс
EventListenerнастроен корректно - Просмотрите логи Pod
EventListener:kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
- Проверьте, достаточно ли прав у стандартного
-
Адрес вебхука (status.addresses) пуст
- Проверьте, что настроенные правила экспорта соответствуют пространству имён вашего
EventListener - Убедитесь, что контроллер автоматического экспонирования запущен:
kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller - Просмотрите логи контроллера на предмет ошибок сопоставления или конфигурации
- Проверьте, что namespace в
namespaceSelector.matchNamesсовпадает с namespace вашегоEventListener
- Проверьте, что настроенные правила экспорта соответствуют пространству имён вашего
-
Триггер не реагирует
- Проверьте доступность URL вебхука (поле
status.addresses) - Убедитесь, что формат запроса корректен
- Просмотрите логи Pod
EventListener:kubectl logs -n tekton-triggers-demo -l app=el-hello-listener - Проверьте корректность настройки
Ingress:kubectl get ingress -n tekton-triggers-demo
- Проверьте доступность URL вебхука (поле
-
TaskRun не создаётся
- Убедитесь в правильности конфигурации
TriggerTemplate - Проверьте сопоставление параметров в
TriggerBinding - Просмотрите логи Pod
EventListenerна наличие ошибок
- Убедитесь в правильности конфигурации