• Русский
  • Быстрый старт

    Это руководство поможет вам начать работу с Tekton Triggers, создав простой сценарий триггера "Hello World" для демонстрации его базовой функциональности. Руководство включает следующие шаги:

    1. Настройка правил автоматического экспонирования EventListener для внешнего доступа
    2. Создание EventListener и связанных ресурсов
    3. Получение автоматически сгенерированного адреса webhook из статуса EventListener

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

    1. Требования к окружению

      • Kubernetes версии 1.21 или выше
      • Установлен Tekton Operator
      • Убедитесь, что Tekton Triggers установлен и готов к работе через Operator
    2. Необходимые инструменты

      • Командная строка kubectl
      • curl (для тестирования триггеров)
    3. Права доступа

      • Требуются привилегии администратора кластера (для настройки правил автоматического экспонирования EventListener)
      • Требуются привилегии администратора пространства имён (для создания ресурсов EventListener)

    Шаг 1: Настройка правил автоматического экспонирования EventListener

    INFO

    О функции автоматического экспонирования

    Это улучшение платформы Alauda (не входит в стандартный Tekton Triggers), которое упрощает настройку внешнего доступа к EventListener.

    Три способа экспонирования EventListener:

    1. Автоматическое экспонирование (улучшение Alauda) ⭐ Рекомендуется для продакшена

      • Автоматически создаёт и управляет ресурсами Ingress
      • Централизованная настройка через TektonConfig
      • URL webhook автоматически заполняются в статусе EventListener
      • Лучший вариант для продакшен-сред с множеством EventListener
    2. Ручное создание Ingress (стандартный подход Tekton)

      • Вы вручную создаёте ресурсы Ingress для каждого EventListener
      • Больше контроля, но требует больше обслуживания
      • Стандартный подход Kubernetes
    3. Port-Forward или NodePort (тестирование/разработка) 🚀 Самый простой старт

      • Не требуется настройка Ingress или DNS
      • Отлично подходит для локального тестирования и обучения
      • См. раздел Простой вариант тестирования, если хотите начать быстро

    Если вы новичок в Triggers, вы можете пропустить этот шаг и перейти к разделу Простой вариант тестирования, чтобы начать с port-forward. Вернитесь к настройке автоматического экспонирования позже, когда будете готовы к продакшен-развёртыванию.

    TIP

    Функция автоматического экспонирования EventListener автоматически создаёт ресурсы Ingress для ваших EventListener на основе настроенных правил экспорта. Это избавляет от необходимости вручную создавать и управлять ресурсами Ingress. Сначала необходимо настроить эти правила, чтобы EventListener были доступны по внешним URL. Подробные инструкции по настройке смотрите в разделе Настройка правил автоматического экспонирования EventListener.

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

    Перед настройкой правил экспорта убедитесь, что у вас есть следующие компоненты:

    1. LoadBalancer или Gateway (рекомендуется для продакшена):

      • Для продакшен-сред рекомендуется использовать LoadBalancer или Gateway для экспонирования EventListener
      • LoadBalancer/Gateway должен быть настроен и доступен
      • У вас должен быть внешний домен или IP-адрес, который будет использоваться для webhook
    2. Ingress Controller (если используется Ingress):

      • В вашем кластере должен быть установлен и запущен контроллер Ingress (например, NGINX, ALB или Traefik)
      • Вы должны знать имя IngressClass, который будет использоваться
      • Подробнее о создании Ingress смотрите в Creating Ingresses.
    3. Домен и сертификат (для HTTPS):

      • Если используется HTTPS, убедитесь, что у вас настроено доменное имя
      • TLS-сертификаты должны быть подготовлены (либо вручную, либо через cert-manager)
    INFO

    Важные замечания:

    • Функция автоматического экспонирования автоматически создаст ресурсы Ingress на основе правил экспорта. Обычно вам не нужно создавать или изменять Ingress вручную.
    • Если вы используете LoadBalancer с нестандартным портом, убедитесь, что порт указан в поле externalHosts (например, https://webhooks.example.com:8443).
    • Для разработки или тестирования можно использовать NodePort вместо Ingress/LoadBalancer. Подробнее смотрите в Пример настройки NodePort.

    Настройка правил экспорта через TektonConfig

    Создайте или обновите ресурс TektonConfig для настройки правил экспорта. Создайте файл tektonconfig.yaml:

    apiVersion: operator.tekton.dev/v1alpha1
    kind: TektonConfig
    metadata:
      name: config
    spec:
      pipeline:
        options:
          configMaps:
            trigger-wrapper-config:
              data:
                config: |
                  export-rules:
                    - name: demo-webhooks
                      host: webhooks.example.com  # Замените на ваш домен. Убедитесь, что настроено разрешение DNS (или добавьте в /etc/hosts для тестирования)
                      ingressClass: nginx  # Замените на ваш ingress класс
                      urlPathPrefix: /triggers
                      externalHosts:
                        - "https://webhooks.example.com"  # Замените на ваш внешний URL (именно его пользователи будут копировать в настройки webhook GitHub/GitLab)
                      namespaceSelector:
                        matchNames:
                          - "tekton-triggers-demo"  # Соответствует вашему демо-пространству имён

    Принцип работы автоматического экспонирования

    Функция автоматического экспонирования работает следующим образом:

    1. Считывает правила экспорта, которые вы настроили в TektonConfig
    2. Автоматически создаёт ресурсы Ingress для EventListener, которые соответствуют правилам
    3. Заполняет поле status.addresses у EventListener URL-адресами webhook, которые можно отображать в UI
    4. Исключает необходимость вручную создавать и управлять ресурсами Ingress для каждого EventListener

    Такой подход обеспечивает централизованное управление способом экспонирования EventListener, упрощая поддержание единых шаблонов URL webhook по всему кластеру.

    Выбор метода настройки Ingress

    Функция автоматического экспонирования поддерживает два метода настройки Ingress для внешнего доступа к EventListener. Выберите метод, который лучше подходит для вашего окружения:

    INFO

    Альтернатива: настройка NodePort

    Если у вас нет LoadBalancer или контроллера Ingress, или вы предпочитаете более простую настройку для разработки/тестирования, можно использовать NodePort. Подробнее смотрите в Пример настройки NodePort. При использовании NodePort функция автоматического экспонирования не требуется, так как доступ к EventListener осуществляется напрямую по IP узла и порту NodePort.

    Метод 1: Общая настройка Ingress (рекомендуется для продакшена)

    Этот метод подходит для большинства Kubernetes-сред. Необходимо:

    1. Создать IngressClass (если ещё не создан): подробности смотрите в Creating Ingresses.

    2. Или использовать сервис LoadBalancer для получения внешнего IP-адреса подробности смотрите в Configure a Load Balancer.

    3. Настроить правила экспорта в соответствии с вашей конфигурацией Ingress:

      • Если используете IngressClass: укажите ingressClass с именем вашего IngressClass (например, nginx)
      • Если используете LoadBalancer: получите внешний IP/домен из сервиса LoadBalancer и настройте поля host и externalHosts соответственно

    Пример конфигурации для IngressClass:

    export-rules:
      - name: demo-webhooks
        host: webhooks.example.com  # Ваш домен. Убедитесь, что настроено разрешение DNS (или добавьте в /etc/hosts для тестирования)
        ingressClass: nginx  # Имя вашего IngressClass
        urlPathPrefix: /triggers
        externalHosts:
          - "https://webhooks.example.com"  # Внешний доступный URL
    WARNING

    Настройка DNS: При указании доменного имени в поле host убедитесь, что:

    • DNS-записи корректно настроены и домен разрешается в IP-адрес вашего Ingress контроллера
    • Для локального тестирования можно добавить домен в /etc/hosts (Linux/Mac) или C:\Windows\System32\drivers\etc\hosts (Windows)
    • Домен должен быть доступен с систем, которые будут отправлять webhook (GitHub, GitLab и др.)

    Метод 2: Быстрый старт для бизнес-кластеров ACP

    Если вы используете бизнес-кластер ACP (Alauda Container Platform), можно использовать встроенный gateway платформы для быстрой настройки:

    1. Получите адрес доступа к платформе ACP (например, https://192.168.1.100)
    2. Узнайте имя вашего кластера (например, test)
    3. Настройте правила экспорта следующим образом:
      • Установите host в пустую строку (или используйте подстановочный знак *)
      • Укажите externalHosts как: <Адрес доступа платформы ACP>/clusters-rewrite/<Имя кластера>
      • Итоговый URL webhook будет: <externalHost>/<urlPathPrefix>/<namespace-eventlistener>/<имя-eventlistener>

    Пример конфигурации для ACP:

    export-rules:
      - name: demo-webhooks
        host: ""  # Пустое или подстановочный знак "*"
        ingressClass: nginx  # Используйте класс ingress по умолчанию
        urlPathPrefix: /triggers
        externalHosts:
          - "https://192.168.1.100/clusters-rewrite/test"  # URL платформы ACP + /clusters-rewrite/<cluster-name>. Итоговый webhook: https://192.168.1.100/clusters-rewrite/test/triggers/tekton-triggers-demo/hello-listener
        namespaceSelector:
          matchNames:
            - "tekton-triggers-demo"

    С такой конфигурацией адрес webhook будет:

    https://192.168.1.100/clusters-rewrite/test/triggers/tekton-triggers-demo/hello-listener
    TIP

    Формула настройки ACP:

    • URL платформы ACP: https://192.168.1.100
    • Имя кластера: test
    • Префикс пути URL: /triggers (настраиваемый)
    • Внешний хост: https://192.168.1.100/clusters-rewrite/test
    • Итоговый URL webhook: 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.

    WARNING

    Важно: Замените значения-заполнители (webhooks.example.com, nginx и т.д.) на ваши реальные домены, класс ingress и URL внешнего хоста. Если у вас нет настроенного домена, можно использовать пустое поле host и указать в externalHosts ваш реальный доступный URL.

    Применение TektonConfig

    $ kubectl apply -f tektonconfig.yaml
    tektonconfig.operator.tekton.dev/config created

    Проверка конфигурации

    Подождите несколько секунд, пока Operator синхронизирует конфигурацию, затем проверьте:

    $ kubectl get configmap trigger-wrapper-config -n tekton-pipelines -o yaml
    apiVersion: v1
    data:
      config: |
        export-rules:
          - name: demo-webhooks
            host: webhooks.example.com
            ...
    kind: ConfigMap
    metadata:
      name: trigger-wrapper-config
      namespace: tekton-pipelines

    В ConfigMap должна содержаться ваша конфигурация правил экспорта. (Примечание: имя ConfigMaptrigger-wrapper-config — это внутреннее техническое имя; запоминать его не нужно, так как управление конфигурацией происходит через TektonConfig.)

    Шаг 2: Создание примерного проекта

    Создание пространства имён

    $ kubectl create namespace tekton-triggers-demo
    namespace/tekton-triggers-demo created
    TIP

    О 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

    Создание Task

    Создайте файл hello-task.yaml:

    apiVersion: tekton.dev/v1
    kind: Task
    metadata:
      name: hello-task
      namespace: tekton-triggers-demo
    spec:
      params:
        - name: message
          description: Message to print
          type: string
          default: "Hello World!"
      steps:
        - name: echo
          image: alpine
          script: |
            echo "$(params.message)"

    Создание Trigger Template

    Создайте файл trigger-template.yaml:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: TriggerTemplate
    metadata:
      name: hello-template
      namespace: tekton-triggers-demo
    spec:
      params:
        - name: message
          description: Message to print
          default: "Hello World!"
      resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: TaskRun
          metadata:
            generateName: hello-run-
            namespace: tekton-triggers-demo
          spec:
            taskRef:
              name: hello-task
            params:
              - name: message
                value: $(tt.params.message)

    Создание Trigger Binding

    Создайте файл trigger-binding.yaml:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: TriggerBinding
    metadata:
      name: hello-binding
      namespace: tekton-triggers-demo
    spec:
      params:
        - name: message
          value: $(body.message)

    Создание Event Listener

    Создайте файл event-listener.yaml:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: EventListener
    metadata:
      name: hello-listener
      namespace: tekton-triggers-demo
    spec:
      # Для корректной работы ServiceAccount с триггерами в том же namespace выполните:
      # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
      serviceAccountName: triggers-default-sa  # Или укажите <ваш service account> для использования кастомного ServiceAccount
      triggers:
        - name: hello-trigger
          bindings:
            - ref: hello-binding
          template:
            ref: hello-template
    INFO

    Примечание по ServiceAccount: Мы используем автоматически созданный дефолтный ServiceAccount (указан serviceAccountName: triggers-default-sa). Этот ServiceAccount создаётся системой Tekton Triggers и имеет права создавать TaskRuns/PipelineRuns в пределах того же пространства имён. Этого достаточно для данного примера, так как все ресурсы находятся в одном namespace. Функция автоматического экспонирования автоматически создаст Ingress для этого EventListener на основе правил экспорта, настроенных на Шаге 1.

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

    Примените все созданные ресурсы:

    $ kubectl apply -f hello-task.yaml
    task.tekton.dev/hello-task created
    
    $ kubectl apply -f trigger-template.yaml
    triggertemplate.triggers.tekton.dev/hello-template created
    
    $ kubectl apply -f trigger-binding.yaml
    triggerbinding.triggers.tekton.dev/hello-binding created
    
    $ kubectl apply -f event-listener.yaml
    eventlistener.triggers.tekton.dev/hello-listener created

    Альтернатива: Простой вариант тестирования

    Если вы пропустили Шаг 1 (настройку автоматического экспонирования) и хотите быстро протестировать, можно использовать port-forward или NodePort для доступа к EventListener без настройки Ingress или DNS.

    Вариант A: Использование Port-Forward (самый простой)

    Ожидание готовности EventListener

    $ kubectl wait --for=condition=Ready eventlistener/hello-listener -n tekton-triggers-demo --timeout=60s
    eventlistener.triggers.tekton.dev/hello-listener condition met

    Проброс локального порта к EventListener

    $ kubectl port-forward -n tekton-triggers-demo svc/el-hello-listener 8080:8080
    Forwarding from 127.0.0.1:8080 -> 8080
    Forwarding from [::1]:8080 -> 8080

    Оставьте этот терминал открытым. Теперь EventListener доступен по адресу http://localhost:8080.

    Отправка тестового запроса через port-forward

    Откройте новый терминал и выполните:

    $ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' http://localhost:8080
    * Connected to localhost (127.0.0.1) port 8080
    > POST / HTTP/1.1
    > Host: localhost:8080
    ...
    < HTTP/1.1 201 Created
    {"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

    Просмотр результатов

    # Просмотр созданного TaskRun
    $ kubectl get taskrun -n tekton-triggers-demo
    NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
    hello-run-xxxxx   True        Succeeded   1m          50s
    
    # Просмотр логов TaskRun
    $ kubectl logs -l triggers.tekton.dev/eventlistener=hello-listener -n tekton-triggers-demo
    Hello, Tekton!

    Вариант B: Использование NodePort

    Для доступа к EventListener снаружи вашей локальной машины без Ingress:

    Патчинг сервиса EventListener на NodePort

    $ kubectl patch svc el-hello-listener -n tekton-triggers-demo -p '{"spec":{"type":"NodePort"}}'
    service/el-hello-listener patched

    Получение NodePort

    $ export NODE_PORT=$(kubectl get svc el-hello-listener -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')
    $ export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}')
    
    # Если NODE_IP пустой, используйте InternalIP
    $ if [ -z "$NODE_IP" ]; then
      export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
    fi
    
    $ echo "EventListener доступен по адресу: http://$NODE_IP:$NODE_PORT"
    EventListener доступен по адресу: http://192.168.1.100:32567

    Отправка тестового запроса через NodePort

    $ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' http://$NODE_IP:$NODE_PORT
    * Connected to 192.168.1.100 (192.168.1.100) port 32567
    > POST / HTTP/1.1
    ...
    < HTTP/1.1 201 Created
    {"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}
    TIP

    Когда использовать каждый метод:

    • Port-forward: локальное тестирование, разработка, обучение
    • NodePort: тестирование с других машин, кластеры для разработки
    • Автоматическое экспонирование (Ingress): продакшен-развёртывания, внешние webhook (GitHub, GitLab и др.)

    Шаг 4: Получение адреса webhook и тестирование (с использованием автоматического экспонирования)

    Ожидание готовности EventListener

    # Ожидание готовности Pod
    $ kubectl get pods -n tekton-triggers-demo
    NAME                                 READY   STATUS    RESTARTS   AGE
    el-hello-listener-xxxxxxxxxx-xxxxx   1/1     Running   0          30s
    
    # Ожидание готовности EventListener
    $ kubectl wait --for=condition=Ready eventlistener/hello-listener -n tekton-triggers-demo --timeout=60s
    eventlistener.triggers.tekton.dev/hello-listener condition met

    Получение автоматически сгенерированного адреса webhook

    Функция автоматического экспонирования автоматически генерирует внешние адреса webhook на основе правил экспорта, настроенных на Шаге 1. Эти адреса заполняются в поле status.addresses у EventListener:

    # Получить первый адрес webhook из status.addresses
    $ export EL_URL=$(kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[0].url}')
    
    # Или просмотреть все доступные адреса
    $ kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[*].url}' | tr ' ' '\n'
    https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener
    https://backup.webhooks.example.com/triggers/tekton-triggers-demo/hello-listener
    TIP

    Формат адреса: Адрес webhook соответствует шаблону: <externalHost>/<urlPathPrefix>/<namespace-eventlistener>/<имя-eventlistener>

    Например: https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener

    Если status.addresses пуст, проверьте:

    • Совпадают ли ваши правила экспорта с namespace EventListener
    • Запущен ли контроллер автоматического экспонирования и обработал ли он EventListener
    • Просмотрите логи контроллера: kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
    WARNING

    Доступность по сети: Убедитесь, что ваш внешний URL доступен с места, откуда вы тестируете. Если тестируете внутри кластера, возможно, потребуется использовать port-forward или обращаться к внутреннему адресу сервиса.

    Проверка доступности домена webhook

    Перед отправкой тестовых запросов проверьте доступность домена webhook:

    # Проверка доступности URL webhook
    # Замените URL на ваш фактический адрес из status.addresses
    curl -I $EL_URL
    
    # Или выполните простой GET-запрос (некоторые webhook могут не поддерживать GET, но это поможет проверить соединение)
    curl -v $EL_URL
    WARNING

    Важно: Убедитесь, что ваш домен webhook, основанный на LoadBalancer/Gateway, доступен из внешних систем. Если вы настраиваете webhook в GitHub, GitLab или других внешних системах, они должны иметь возможность достучаться до этого URL. Проверьте:

    • Корректность DNS-записей
    • Правильность настройки и доступность LoadBalancer/Gateway
    • Правила firewall, разрешающие входящий трафик
    • Валидность TLS-сертификатов (если используется HTTPS)

    Отправка тестового запроса на webhook

    $ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' $EL_URL
    * Connected to webhooks.example.com (xx.xx.xx.xx) port 443
    > POST /triggers/tekton-triggers-demo/hello-listener HTTP/1.1
    > Host: webhooks.example.com
    ...
    < HTTP/1.1 201 Created
    {"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

    Просмотр результатов

    # Просмотр созданного TaskRun
    $ kubectl get taskrun -n tekton-triggers-demo
    NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
    hello-run-xxxxx   True        Succeeded   1m          50s
    
    # Просмотр логов конкретного TaskRun
    $ kubectl logs -l eventlistener=hello-listener -n tekton-triggers-demo
    Hello, Tekton!

    Очистка ресурсов

    После тестирования вы можете удалить созданные ресурсы:

    $ kubectl delete namespace tekton-triggers-demo
    namespace "tekton-triggers-demo" deleted

    Следующие шаги

    Теперь, когда вы успешно создали и протестировали базовый пример Tekton Triggers, вы можете:

    1. Изучить концепции Tekton Triggers
    2. Узнать, как использовать Настройку EventListener для типовых инструкций
    3. Настроить правила автоматического экспонирования EventListener для продвинутых сценариев
    4. Настроить и использовать события GitLab для запуска pipeline

    Часто задаваемые вопросы

    1. Pod EventListener не запускается

      • Проверьте, что у дефолтного ServiceAccount достаточно прав в пределах namespace
      • Убедитесь, что ресурс EventListener настроен корректно
      • Просмотрите логи Pod EventListener: kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
    2. Адрес webhook (status.addresses) пуст

      • Проверьте, что правила экспорта соответствуют namespace вашего EventListener
      • Убедитесь, что контроллер автоматического экспонирования запущен: kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller
      • Просмотрите логи контроллера на предмет ошибок сопоставления или конфигурации
      • Убедитесь, что namespace в namespaceSelector.matchNames совпадает с namespace вашего EventListener
    3. Триггер не реагирует

      • Проверьте доступность URL webhook (поле status.addresses)
      • Убедитесь, что формат запроса корректен
      • Просмотрите логи Pod EventListener: kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
      • Проверьте правильность настройки Ingress: kubectl get ingress -n tekton-triggers-demo
    4. TaskRun не создаётся

      • Убедитесь, что конфигурация TriggerTemplate корректна
      • Проверьте сопоставление параметров в TriggerBinding
      • Просмотрите логи Pod EventListener на наличие ошибок