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

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

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

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

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

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

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

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

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

    INFO

    Об автоматическом экспонировании

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

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

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

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

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

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

    TIP

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

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

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

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

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

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

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

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

    • Функция автоматического экспонирования автоматически создаст для вас ресурсы Ingress на основе правил экспорта. Обычно вручную создавать или изменять ресурсы Ingress не требуется.
    • Если вы используете LoadBalancer с пользовательским портом, обязательно укажите порт в поле externalHosts (например, https://webhooks.example.com:8443).
    • Для development- или testing-окружений можно использовать 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 class
                      urlPathPrefix: /triggers
                      externalHosts:
                        - "https://webhooks.example.com"  # Замените на свой внешний URL (именно его пользователи будут копировать в настройки webhook GitHub/GitLab)
                      namespaceSelector:
                        matchNames:
                          - "tekton-triggers-demo"  # Сопоставьте ваш demo namespace

    Как работает автоматическое экспонирование

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

    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 controller, либо вы предпочитаете более простую схему для development/testing, можно использовать NodePort. Подробности см. в примере настройки NodePort. При использовании NodePort функция автоматического экспонирования не требуется, поскольку доступ к EventListener будет осуществляться напрямую через IP-адрес узла и NodePort.

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

    Этот способ подходит для большинства окружений Kubernetes. Вам нужно:

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

    2. Или использовать Service LoadBalancer, чтобы получить внешний IP-адрес подробнее см. в Настройка 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 controller
    • Для локального тестирования можно добавить домен в /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 пустым (или используйте wildcard *)
      • Установите externalHosts в: <Адрес доступа к платформе ACP>/clusters-rewrite/<Имя кластера>
      • Итоговый URL webhook будет: <externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>

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

    export-rules:
      - name: demo-webhooks
        host: ""  # Пустое значение или wildcard "*"
        ingressClass: nginx  # Используйте default ingress class
        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 (настраивается)
    • External Host: https://192.168.1.100/clusters-rewrite/test
    • Итоговый URL webhook: https://192.168.1.100/clusters-rewrite/test/triggers/<eventlistener-namespace>/<eventlistener-name>

    Пример: если адрес платформы ACP — https://192.168.1.100, имя кластера — test, а urlPathPrefix/triggers, то адрес доступа будет https://192.168.1.100/clusters-rewrite/test/triggers.

    WARNING

    Важно: Замените значения-заполнители (webhooks.example.com, nginx и т. д.) на ваше реальное доменное имя, ingress class и URL внешнего host. Если домен не настроен, можно использовать пустое поле 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 должен содержать вашу конфигурацию правил экспорта. (Примечание: имя ConfigMap trigger-wrapper-config — это внутреннее техническое имя; запоминать его не нужно, поскольку вы управляете конфигурацией через TektonConfig.)

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

    Создание namespace

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

    О ServiceAccount для EventListener

    В этом quick start мы используем default ServiceAccount, который автоматически создается системой Tekton Triggers. Этот ServiceAccount называется triggers-default-sa и имеет права, ограниченные namespace.

    Как это работает:

    • При установке Tekton Triggers он автоматически создает default ServiceAccount в каждом namespace
    • Его можно найти, выполнив: kubectl get sa -n tekton-triggers-demo -l triggers.tekton.dev/default-service-account
    • Этот ServiceAccount имеет права на создание TaskRuns и PipelineRuns в пределах того же namespace
    • Ручная настройка не требуется — достаточно ссылаться на него по имени: triggers-default-sa

    Когда нужен пользовательский ServiceAccount:

    • Если требуется создавать ресурсы в нескольких namespace (cross-namespace triggers)
    • Если нужны дополнительные права сверх стандартной области действия
    • См. Setup 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:
      # Run the following order to get ServiceAccount works for triggers within the same namespace
      # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
      serviceAccountName: triggers-default-sa  # Or set to <your service account> to use a custom ServiceAccount
      triggers:
        - name: hello-trigger
          bindings:
            - ref: hello-binding
          template:
            ref: hello-template
    INFO

    Примечание о ServiceAccount: Мы используем автоматически созданный default ServiceAccount (задав serviceAccountName как triggers-default-sa). Этот ServiceAccount создается системой Tekton Triggers и имеет права на создание TaskRuns/PipelineRuns в пределах того же namespace. Этого достаточно для данного примера, поскольку все ресурсы находятся в одном 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:

    Измените Service 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}')
    
    # If NODE_IP is empty, use InternalIP
    $ if [ -z "$NODE_IP" ]; then
      export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
    fi
    
    $ echo "EventListener accessible at: http://$NODE_IP:$NODE_PORT"
    EventListener accessible at: 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: тестирование с других машин, development-кластеры
    • Автоматическое экспонирование (Ingress): deployment в production, внешние 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>/<eventlistener-namespace>/<eventlistener-name>

    Например: 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 host доступен из среды, в которой вы тестируете. Если тестирование выполняется внутри кластера, может потребоваться использовать port-forward или обращаться к внутреннему адресу service.

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

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

    # Проверить, доступен ли URL webhook
    # Замените URL на фактический адрес webhook из status.addresses
    curl -I $EL_URL
    
    # Или выполните простой GET-запрос (некоторые endpoints 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. Узнать, как использовать Setup EventListeners для общих инструкций по настройке
    3. Настроить правила автоматического экспонирования EventListener для более сложных сценариев экспонирования
    4. Настроить и использовать события GitLab для запуска pipeline

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

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

      • Проверьте, достаточно ли у default 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. Trigger не отвечает

      • Убедитесь, что 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