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

    Это руководство поможет вам начать работу с 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 вебхуков автоматически заполняются в статусе 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-адрес, который будет использоваться для вебхуков
    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 вебхуков, которые можно отображать в UI
    4. Исключает необходимость вручную создавать и управлять ресурсами Ingress для каждого EventListener

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

    Выбор метода конфигурации 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)
    • Домен должен быть доступен с систем, которые будут отправлять вебхуки (GitHub, GitLab и др.)

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

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

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

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

    export-rules:
      - name: demo-webhooks
        host: ""  # Пустое или используйте wildcard "*"
        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"

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

    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 вебхука: 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

    Создание задачи

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

    apiVersion: tekton.dev/v1
    kind: Task
    metadata:
      name: hello-task
      namespace: tekton-triggers-demo
    spec:
      params:
        - name: message
          description: Сообщение для вывода
          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: Сообщение для вывода
          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 с триггерами в том же пространстве имён выполните:
      # $ 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 в пределах того же пространства имён. Этого достаточно для данного примера, так как все ресурсы находятся в одном пространстве имён. Функция автоматического экспонирования автоматически создаст 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): продакшен-развёртывания, внешние вебхуки (GitHub, GitLab и др.)

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

    Ожидание готовности 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

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

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

    # Получить первый адрес вебхука из 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

    Формат адреса: Адрес вебхука имеет шаблон: <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
    WARNING

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

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

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

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

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

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

    Отправка тестового запроса на вебхук

    $ 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 в пространстве имён
      • Убедитесь, что ресурс EventListener настроен корректно
      • Просмотрите логи Pod EventListener: kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
    2. Адрес вебхука (status.addresses) пуст

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

      • Проверьте доступность URL вебхука (поле 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 на наличие ошибок