logo
Alauda DevOps Pipelines Docs
English
简体中文
English
简体中文
logo
Alauda DevOps Pipelines Docs
导航

概览

介绍
架构
快速开始
生命周期策略
发版日志
特性概述

触发器

介绍
架构

核心概念

Tekton Triggers 核心概念
EventListener
触发器
Interceptor
TriggerBinding
TriggerTemplate
快速开始

实用指南

设置事件监听器
使用 GitLab 事件触发器
创建 TriggerTemplate

问题处理

Pipeline 未被自动触发
permissions

概念

TektonConfig
TektonPipeline
安装

升级

升级路径
升级 Alauda DevOps Pipelines Operator

配置

调整子组件的可选配置项
配置流水线组件的资源配额
Pod 模板配置指南
定期清理 TaskRun 和 PipelineRun 资源

How To

通过 TektonConfig 在 global 集群中部署 tekton-pipelines

管道

介绍
架构

概念

任务
TaskRuns
流水线
PipelineRuns
StepActions
解析器
工作空间
Pod 模板
快速开始

实用指南

调整 Dockerfile 构建适用于 Task 的自定义镜像
Specifying remote pipelines using hub resolvers
Specifying remote tasks using hub resolvers
使用 java-image-build-scan-deploy 管道

故障排查

在 Tekton 中使用自定义镜像时遇到容器创建失败的问题
在 run-script Task 中使用自定义镜像时遇到权限不够的问题
在 Tekton 中遇到无法使用多个基于 PVC 的工作区的问题
权限

结果

介绍
架构

核心概念

核心概念
深入理解 Tekton Results
快速开始
permissions

配置

数据库配置

供应链安全

介绍
架构

概念

核心概念
了解 Tekton Chains

快速开始

Getting Started
签名证明

实用指南

生成镜像签名并验证镜像完整性
构建系统溯源验证
源代码仓库验证
漏洞扫描和验证
Base Image and SBOM Verification
License Compliance Verification
Keyless Signing Verification

配置

链配置
链配置
Authentication for Chains
签名密钥配置

Hub

引言
架构

核心概念

概念
理解 Tekton Hub
权限描述

API Reference

介绍

Kubernetes APIs

Operator

TektonConfig [operator.tekton.dev/v1alpha1]
TektonInstallerSet [operator.tekton.dev/v1alpha1]
TektonPipeline [operator.tekton.dev/v1alpha1]
TektonTrigger [operator.tekton.dev/v1alpha1]
TektonChain [operator.tekton.dev/v1alpha1]
TektonHub [operator.tekton.dev/v1alpha1]
TektonResult [operator.tekton.dev/v1alpha1]
TektonInstallerSet [operator.tekton.dev/v1alpha1]
OpenShift Pipelines as Code [operator.tekton.dev/v1alpha1]

管道

Pipeline [tekton.dev/v1]
任务 [tekton.dev/v1]
PipelineRun [tekton.dev/v1]
TaskRun [tekton.dev/v1]
集群任务 [tekton.dev/v1]
运行 [tekton.dev/v1]
CustomRun [tekton.dev/v1]
StepAction [tekton.dev/v1]
VerificationPolicy [tekton.dev/v1alpha1]
ResolutionRequest [resolution.tekton.dev/v1beta1]

Triggers

触发器 [triggers.tekton.dev/v1beta1]
TriggerTemplate [triggers.tekton.dev/v1beta1]
EventListener [triggers.tekton.dev/v1beta1]
触发绑定 [triggers.tekton.dev/v1beta1]
拦截器 [triggers.tekton.dev/v1alpha1]
集群触发器绑定 [triggers.tekton.dev/v1beta1]
集群拦截器 [triggers.tekton.dev/v1alpha1]

高级 API

Results

Introduction to API Usage
Results 列表
结果详情
结果记录列表
Result logs 列表
📝 在 GitHub 上编辑此页
上一页TriggerBinding
下一页快速开始

#TriggerTemplate

TriggerTemplate 是 Tekton Triggers 中的一个强大组件,用于定义在检测到事件时应创建的资源蓝图。它作为事件驱动流水线的动作部分,明确指定应响应事件实例化哪些 Kubernetes 资源(通常是 TaskRuns 或 PipelineRuns)。

#目录

#术语说明

术语说明
TriggerTemplate定义在检测到事件时应创建哪些资源的 Tekton 资源。
ResourceTemplate在 TriggerTemplate 中定义的 Kubernetes 资源规范,用于创建资源。
ParameterTriggerTemplate 中的变量,可通过 TriggerBindings 从事件负载中填充数据。
$(tt.params.x)在资源模板中引用参数的语法。
generateNameKubernetes 元数据字段,通过添加随机后缀创建唯一名称的资源。

#为什么需要 TriggerTemplate

#事件驱动资源创建的挑战

在响应外部事件的 CI/CD 系统中,创建资源时会遇到以下挑战:

  1. 动态资源创建:需要根据每个事件的特定信息创建资源,如流水线。
  2. 参数化:不同事件需要传递不同参数给流水线。
  3. 可复用性:相同的资源创建模式通常需要在多个事件间复用。
  4. 模板化:为每种事件类型手动创建资源容易出错且不具扩展性。

如果没有 TriggerTemplates,解决这些问题将需要:

  • 为每个事件编写自定义脚本生成 Kubernetes 资源
  • 处理复杂的参数替换逻辑
  • 在不同事件处理器间重复定义资源
  • 手动同步事件数据与资源创建

#TriggerTemplate 如何解决这些问题

TriggerTemplate 提供了一种声明式、Kubernetes 原生的方式来:

  1. 定义资源蓝图:明确指定事件发生时应创建哪些资源。
  2. 参数化资源:使用从事件中提取的参数定制资源。
  3. 确保一致性:为类似事件一致地创建结构相同的资源。
  4. 职责分离:将事件检测(EventListener)和数据提取(TriggerBinding)与资源创建解耦。
  5. 支持复用:定义一次模板,可在多个触发器中复用。

这种方法为事件检测时应执行的操作提供了清晰、声明式的定义,使 CI/CD 系统更易维护和扩展。

#优势

  • 声明式定义:使用 Kubernetes 原生 YAML 定义要创建的资源
  • 参数化:动态使用事件数据定制资源
  • 复用性:模板定义一次,可跨多个触发器复用
  • 职责分离:事件检测、数据提取与资源创建清晰分离
  • 默认值支持:为可能缺失的参数提供默认值
  • 动态命名:生成唯一命名资源避免冲突
  • 多资源创建:单个事件可创建多个资源
  • 资源校验:资源在运行时创建前进行校验

#适用场景

TriggerTemplates 在以下场景中必不可少:

  1. 自动化 CI/CD 流水线:代码推送或拉取请求打开时自动创建流水线运行。
  2. 多环境部署:使用相同模板,传入不同参数部署到多个环境。
  3. 事件驱动工作流:响应外部系统事件(如问题更新或监控告警)创建资源。
  4. 动态资源创建:根据事件特定参数(如提交 ID 或分支名)生成资源。
  5. 参数化测试:根据事件类型创建不同参数的测试流水线。

#约束与限制

  • TriggerTemplates 中的参数只能是字符串值
  • 使用 JSON 对象作为参数时需谨慎处理
  • 资源校验发生在运行时,而非创建时
  • 非 Tekton 资源可能需要扩展默认服务账户权限
  • 嵌入资源必须包含在使用它们的 PipelineRun 或 TaskRun 中
  • 带数字前缀的参数名需特殊处理

#原则

#TriggerTemplate 结构

TriggerTemplate 主要包含两个部分:

  1. 参数定义:声明可在资源模板中使用的参数
  2. 资源模板:定义要创建的 Kubernetes 资源
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: example-template
spec:
  params:
    - name: param1
      description: 参数 1 的描述
      default: default-value  # 可选默认值
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: example-pipeline-run-
      spec:
        pipelineRef:
          name: example-pipeline
        params:
          - name: pipeline-param
            value: $(tt.params.param1)

#参数处理

TriggerTemplates 中参数遵循以下原则:

  1. 声明:参数必须在 params 部分声明,包含名称,可选描述和默认值。
  2. 引用:资源模板中使用 $(tt.params.参数名) 语法引用参数。
  3. 默认值:若 TriggerBinding 未提供参数,则使用默认值(如有)。
  4. 字符串值:所有参数值均视为字符串,即使表示数字或 JSON 对象。
  5. 特殊字符:带数字前缀或特殊字符的参数在资源模板中可能需加引号。

#资源模板创建流程

事件被检测和处理时:

  1. EventListener 接收事件
  2. 拦截器(若配置)处理和过滤事件
  3. TriggerBindings 从事件中提取数据
  4. TriggerTemplate 接收提取的参数
  5. 在资源模板中进行参数替换
  6. 创建带替换值的 Kubernetes 资源

每个创建的资源都会带有标签以追踪其来源:

  • tekton.dev/eventlistener: <EventListenerName>
  • tekton.dev/triggers-eventid: <EventID>

#配置示例

#基础 CI 流水线模板

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: ci-pipeline-template
spec:
  params:
    - name: git-revision
      description: Git 提交 SHA
    - name: git-repo-url
      description: Git 仓库 URL
    - name: git-repo-name
      description: Git 仓库名称
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: $(tt.params.git-repo-name)-ci-
      spec:
        pipelineRef:
          name: ci-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
          - name: repo-url
            value: $(tt.params.git-repo-url)
        workspaces:
          - name: source
            emptyDir: {}

#多环境部署模板

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-template
spec:
  params:
    - name: environment
      description: 部署环境
      default: development
    - name: image-tag
      description: 部署的镜像标签
    - name: app-name
      description: 应用名称
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: deploy-$(tt.params.app-name)-$(tt.params.environment)-
      spec:
        pipelineRef:
          name: deployment-pipeline
        params:
          - name: target-environment
            value: $(tt.params.environment)
          - name: image-tag
            value: $(tt.params.image-tag)
          - name: application
            value: $(tt.params.app-name)

#多资源模板示例

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: multi-resource-template
spec:
  params:
    - name: git-revision
      description: Git 提交 SHA
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: build-pipeline-
      spec:
        pipelineRef:
          name: build-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        generateName: test-pipeline-
      spec:
        pipelineRef:
          name: test-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)

#与 TriggerTemplate 相关的重要参数说明

#参数替换

参数替换是 TriggerTemplates 动态和可复用的核心机制。

#适用场景

  • 在 PipelineRuns 中插入提交 SHA
  • 在流水线参数中使用仓库 URL 和分支名
  • 向流水线传递事件元数据
  • 使用事件特定信息定制资源名称

#约束与限制

  • 仅支持字符串值
  • JSON 对象需特殊处理
  • 带数字前缀的参数可能需加引号

#原则/参数说明

参数替换语法为 $(tt.params.参数名),其中 参数名 是 TriggerTemplate params 部分定义的参数名称。

例如:

params:
  - name: git-revision
    description: Git 提交 SHA
resourcetemplates:
  - apiVersion: tekton.dev/v1beta1
    kind: PipelineRun
    spec:
      params:
        - name: revision
          value: $(tt.params.git-revision)

#JSON 处理

在 TriggerTemplates 中处理 JSON 数据时需注意特殊事项。

#适用场景

  • 向流水线传递复杂数据结构
  • 处理包含嵌套 JSON 的 webhook 负载
  • 创建需要 JSON 配置的资源

#约束与限制

  • JSON 对象必须作为字符串处理
  • 转义引号较为复杂
  • 旧版模板可能需特殊注解

#原则/参数说明

处理 JSON 对象时:

  1. 在资源模板中使用时,不要将 JSON 参数用引号包裹
  2. 对于需要转义引号的旧版模板,添加注解:
    metadata:
      annotations:
        triggers.tekton.dev/old-escape-quotes: "true"

#参考资料

  • Tekton Triggers Documentation
  • TriggerTemplate Official Documentation
  • Tekton Pipelines Documentation
  • Kubernetes Resource Management