Tekton Triggersによるwebhook追加

Tekton Triggersは、Tekton Pipelinesにwebhookを追加する機能です。POSTリクエストからタスクを起動します。
CronJobからwebhookを呼ぶことで定時バッチの実行も可能です。

Tektonプロダクト群のうち、ベースであるPipelinesが先行してv1.0GAとなりましたが、Triggersはまだベータ段階であり、安定動作やログ出力の面で完成されていない面があります。

CronJobやクラスタ内のリクエストであれば、Triggersを用いず直接PipelineRunを起動する方法も考えられます。

前提条件

まず、 Tekton Pipelinesをセットアップし、tknコマンドでタスク実行可能な状態を確認しておく必要があります。
TriggerはPipelineを呼び出す構造になっています。

TriggersとInterceptorのアドオンは、以下のようにkubectl applyでインストールできます。PipelineはLTSバージョンを設定していますが、Triggersにはないため最新版をおおむね採用することになります。
基礎的なwebhookはIntercepterなしでも動作しますが、ルーティングにInterceptorが必要になります。

$ kubectl apply --filename https://storage.googleapis.com/tekton-releases/triggers/latest/release.yaml
$ kubectl apply --filename https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.yaml

また、TriggersのEventListenerはクラスタリソースにアクセスするためのServiceAccountを必要とします。
Configure your clusterセクションに説明があります。サービスアカウントを含むRBACはkubernetesの標準機能を用いて実装します。

Examplesのrbac.yamlにミニマム権限を設定したmanifest例があるので、流用すると良いでしょう。Triggersインストール時に登録されたClusterRoleを利用するServiceAccountをセットアップするものです。

Tekton Triggersの構成

Triggerの主要リソースは、EventListener, TriggerTemplate, TriggerBindingの3つです。

EventListenerは、ServiceとDeploymentを生成しデーモンプロセスとして動作し、port8080でHTTPリクエストをlistenします。既述のServiceAccountが必要です
TriggerTemplateは、実行対象のPipelineを参照します。また、params以外の詳細オプションはTriggerTemplateに指定します
TriggerBindingは、リクエストbodyのJSONデータなどをparamsにマップします。Pipelineに変数を供給する必要がないケースでは作成する必要がありません

これらを組み合わせて、HTTPリクエストをPipelinesのリソースに変換します。

EventListenerの概要

Triggersは、EventListenerの性質を把握すると理解が進みます。ドキュメントされていない特徴として、以下のような実装になっています。

tkn eventlistenerコマンドで操作できます。
- 起動ログやリクエストの処理状況はlogsサブコマンドで確認可能
- セットアップ時にconfigMapを読めないなどの権限エラーが出ている場合には、概ねServiceAccountの設定不良
httpリクエストのエンドポイントはel-<listener_name>という名前のServiceです。
- クラスタ内部からhttp://el-<listener_name>.<namespace>.svc.cluster.local:8080にリクエストするとTriggerを実行可能
- curlなどのプリミティブなhttpクライアントからリクエスト可能
- サービスをクラスタ外に公開するには、認証を考慮のうえk8sの標準的な方法で追加セットアップが必要
EventListenerは1インスタンスではなく、TriggerTemplateの数だけ立ち上がります

paramsの挙動

Tektonはparamsのうちdefaultを設定したパラメータが全般的に省略可能ですが、TriggersへのhttpリクエストではTriggerTemplateにdefault設定したパラメータのみ省略可能です。

ほかにPipelineやTaskのレイヤでもdefault設定可能ですが、これらは参照されません。

TriggerTemplate

TriggerTemplatesは、spec.resourcetemplatesにPipelineRunを記述することでタスクを起動するリソースです。spec.pipelineRefでターゲットのPipelineを指定し、主にspec.paramsやspec.workspacesといったTektonの基礎的なリソースを割り当てます。

他にも PipelineRunスペックの項目を設定できます。

直感的ではないポイントとして、serviceAccountNameやpodTemplateなどTaskRunに指定するオプションは、spec.resourceTemplates.[].spec.taskRunTemplateに定義します。

たとえば、タスク内でkubectlを実行したいケースではRoleを用いた適切な権限が必要になるでしょう。ServiceAccountのセットアップはkubernetes標準のリソースで実装でき、そのServiceAccountをTektonのTaskRunから参照します。
同様に、affinityなどkubernetes標準のpodSpecはtaskRunTemplate.podTemplateに記述できます。

TriggerTemplateの全構成は API仕様を参照してください。

Tekton Triggersのメリット

Triggersを実装することで、tknコマンドの実行環境をセットアップすることなく一般的なhttpクライアントからPipelineを実行できます。

また、Cronについてはk8s標準の CronJosを用いたTriggerリクエスト実装パターンがコミュニティの暫定ベストプラクティスになっているようです。

トラブルシュート

params変更の反映

一度設定したTriggerTemplateやTriggerBindingは更新可能ですが、kubectl applyで差分更新が効かないケースがあります。
その場合、kubectl delete -> kubectl createすると反映できます。

パラメータの不調については、tekton-cliをインストールのうえtkn triggerbinding describeやtkn triggertemplate describeを実行すると、現在受け付けているパラメータ一覧を確認できます。

ログレベルを一時的に変更

Configuring debug logging for EventListenersの解説のとおり、configmap/config-logging-triggersを変更するとログレベルを変えられます。kubectl patchのほかkubectl editで編集することも可能です。

ただしConfigMapはtektonをバージョンアップすると上書きされ、恒久的な設定方法はありません。Triggersはログが冗長で抑止する手段がないため、実運用にはフィルタツールが不可欠であると思います。

証明書エラー

interceptorにリクエストを送ってもタスクが起動しない場合、TLS証明書のエラーが起きているケースがあります。
triggers-webhook-cert expired after a yearで失効ケースの報告がありますが、アップグレード後に証明書の更新が失敗することもあります。

イベントリスナーやinterceptorのログを確認するとTLS証明書エラーを確認できます。

$ kubectl logs deploy/<EventListener name>
$ kubectl logs -ntekton-pipelines deploy/tekton-triggers-core-interceptors

証明書の再作成で対処できます。証明書はコンテナ起動時に作成する挙動のようです。

$ kubectl delete -ntekton-pipelines secret triggers-webhook-certs
$ kubectl delete -ntekton-pipelines secret tekton-triggers-core-interceptors-certs
$ kubectl rollout restart -ntekton-pipelines deploy tekton-triggers-core-interceptors

なお、このエラーは膨大な量のエラーログを出力するため、放置するとロギング課金を食いつぶすことがあり得ます。

EventListenerのQoS強化

EventListenerはDeploymentを作成します。デフォルトでは QoSがBestEffortであり、リソースが逼迫してくると優先的に停止されることで、タスクを実行できないケースがあります。

QoSを変更するには、以下のようにリソース要求を設定します。limitsを利用してGuaranteedも指定可能でしょう。

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
spec:
  resources:
    kubernetesResource:
      spec:
        template:
          spec:
            containers:
            - resources:
                requests:
                  cpu: 50m
  triggers:

kubernetesResourceについては、 EventListernerのdocに説明がありますが、API仕様が厳密ではない点に注意が必要です。

⁋ 2021/07/06↻ 2025/09/10