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

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

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

    Требования

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

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

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

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

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

    INFO

    Об автоматическом предоставлении доступа

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

    Три способа предоставить доступ к EventListener:

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

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

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

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

    TIP

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

    Требования

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

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

      • Для production-окружений рекомендуется использовать LoadBalancer или Gateway для предоставления доступа к EventListeners
      • 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).
    • Для окружений разработки или тестирования вы также можете использовать 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 для EventListeners, которые соответствуют правилам
    3. Заполняет поле status.addresses у EventListener URL webhook, которые можно отобразить в UI
    4. Устраняет необходимость вручную создавать и управлять ресурсами Ingress для каждого EventListener

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

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

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

    INFO

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

    Если у вас нет LoadBalancer или Ingress controller, либо вы предпочитаете более простую настройку для разработки/тестирования, можно использовать 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/домен из service 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 Business Clusters

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

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

    Пример настройки для 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"

    При такой настройке адрес 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/<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 и настроить 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

    Для этого быстрого старта мы будем использовать 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

    Когда нужен custom ServiceAccount:

    • Если вам нужно создавать ресурсы в нескольких namespace (cross-namespace triggers)
    • Если вам нужны дополнительные права, выходящие за пределы default scope
    • См. Настройка EventListener для конфигурации custom 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 работал для triggers внутри одного namespace
      # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
      serviceAccountName: triggers-default-sa  # Или укажите <your service account>, чтобы использовать 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}')
    
    # Если 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 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): 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
    • Запущен ли controller автоматического предоставления доступа и обработал ли он EventListener
    • Логи controller: kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
    WARNING

    Сетевой доступ: Убедитесь, что внешний URL хоста доступен из места, откуда вы выполняете тест. Если вы тестируете внутри кластера, может потребоваться использовать 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. Узнать, как использовать Настройка EventListeners для общих инструкций по настройке
    3. Настроить правила автоматического предоставления доступа к EventListener для более сложных сценариев предоставления доступа
    4. Настроить и использовать события Gitlab для запуска pipelines

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

    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
      • Проверьте, что controller автоматического предоставления доступа запущен: kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller
      • Посмотрите логи 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