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

#Interceptor

Interceptor 是 Tekton Triggers 中一个强大的组件,用于在事件数据到达 TriggerBindings 和 TriggerTemplates 之前对其进行处理和过滤。它充当传入 webhook 事件的守门员和转换器,允许您验证、过滤和修改事件数据,确保只有相关事件触发您的流水线。

#目录

#术语解释

术语说明
Interceptor在事件数据到达 TriggerBindings 和 TriggerTemplates 之前处理 webhook 事件的组件。
ClusterInterceptor集群范围的 Interceptor,可跨所有命名空间使用。
CELCommon Expression Language,用于过滤和转换事件数据。
ExtensionsInterceptor 添加的额外数据字段,可被 TriggerBindings 访问。
Webhook当外部系统发生特定事件时,发送事件数据的 HTTP 回调。

#为什么需要 Interceptors

#事件处理的挑战

在响应外部事件的 CI/CD 系统中,会遇到以下几个挑战:

  1. 事件验证:需要验证外部 webhook 以确保其来自可信来源。
  2. 事件过滤:并非所有事件都应触发流水线,需要根据事件类型或内容进行过滤。
  3. 数据转换:原始 webhook 负载通常包含多余数据或需要重构。
  4. 安全问题:如果没有适当验证,webhook 端点可能容易受到滥用。

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

  • 针对每个 webhook 源编写自定义验证代码
  • 在流水线定义中嵌入复杂逻辑
  • 在脚本中手动进行过滤和转换
  • 为每个集成实现独立的安全机制

#Interceptors 如何解决这些问题

Interceptors 提供了一种标准化、声明式的方式来:

  1. 验证事件:验证 webhook 签名和令牌以确保真实性。
  2. 过滤事件:仅处理基于类型、内容或其他条件的相关事件。
  3. 转换数据:提取、修改或添加数据,使其更适合流水线使用。
  4. 增强安全性:在所有 webhook 集成中实施一致的安全实践。
  5. 模块化逻辑:将事件处理与流水线执行分离。

这种方法在事件接收、处理和流水线执行之间创建了清晰的分离,使您的 CI/CD 系统更易维护且更安全。

#优势

  • 增强安全性:在处理前验证 webhook 的真实性
  • 降低流水线复杂度:将过滤和转换逻辑移出流水线
  • 标准化处理:对不同来源的事件进行一致处理
  • 灵活性:可串联多个 interceptor 以满足复杂处理需求
  • 可扩展性:可创建自定义 interceptor 以满足特殊处理需求
  • 可重用性:定义一次 interceptor,可在多个触发器中复用
  • 声明式配置:使用 Kubernetes 资源配置事件处理

#适用场景

Interceptor 在以下场景中至关重要:

  1. 安全的 webhook 处理:需要验证 webhook 事件来自可信来源时。

  2. 条件流水线执行:仅在特定事件类型或内容(例如仅在 main 分支的 push 事件)触发流水线时。

  3. 数据丰富:需要添加计算值或从复杂事件负载中提取特定数据时。

  4. 多源集成:集成多个 webhook 提供商(GitHub、GitLab、Bitbucket)并实现一致处理时。

  5. 自定义事件处理:实现标准 interceptor 之外的特殊事件处理逻辑时。

#约束和限制

  • Interceptor 会增加事件处理的开销
  • 复杂的 CEL 表达式可能难以调试
  • 自定义 interceptor 需要额外的部署和管理
  • 推荐使用 HTTPS,HTTP 支持将在未来版本中移除
  • Interceptor 必须妥善保护以防止未授权访问

#原则

#Interceptor 架构

Interceptor 位于 EventListener 和 Trigger 处理流水线之间:

  1. EventListener 接收 webhook 事件
  2. Interceptors 处理并过滤事件
  3. TriggerBindings 从处理后的事件中提取数据
  4. TriggerTemplates 使用提取的数据创建资源

Interceptor 可以串联,每个 interceptor 接收上一个的输出。这允许构建复杂的处理流水线,每个 interceptor 执行特定功能。

#Interceptor 类型

Tekton Triggers 支持两种 interceptor 实现:

  1. 独立 Interceptor:作为独立的 Kubernetes 服务实现

    • Interceptor:命名空间范围的自定义资源
    • ClusterInterceptor:集群范围的自定义资源
    • 更灵活且易于扩展
    • 可用任何支持 HTTP 服务的语言实现
  2. 内置 Interceptor:包含在 EventListener Pod 中

    • GitHub、GitLab、Bitbucket、CEL 等
    • 保留以兼容旧版本
    • 使用更简单但扩展性较差

#Interceptor 结构

一个基本的 Interceptor 资源结构如下:

apiVersion: triggers.tekton.dev/v1alpha1
kind: Interceptor
metadata:
  name: my-interceptor
spec:
  clientConfig:
    service:
      name: my-interceptor-svc
      namespace: default
      path: "/optional-path"  # 可选
      port: 8081  # 默认为 80

在 Trigger 中引用时:

triggers:
  - name: trigger-with-interceptor
    interceptors:
      - ref:
          name: "my-interceptor"
          kind: Interceptor  # 或 ClusterInterceptor
          namespace: default  # 仅 Interceptor 需要
        params:  # 可选参数
          - name: "param1"
            value: "value1"

#配置示例

#GitHub Interceptor 示例

triggers:
  - name: github-push-trigger
    interceptors:
      - ref:
          name: "github"
        params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["push"]
          - name: "branches"
            value: ["main", "release/*"]

#GitLab Interceptor 和 CEL 示例

triggers:
  - name: gitlab-merge-request-trigger
    interceptors:
      - ref:
          name: "gitlab"
        params:
          - name: "secretRef"
            value:
              secretName: gitlab-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["Merge Request Hook"]
      - ref:
          name: "cel"
        params:
          - name: "filter"
            value: "body.object_attributes.state == 'opened' || body.object_attributes.state == 'reopened'"
          - name: "overlays"
            value:
              - key: truncated_sha
                expression: "body.object_attributes.last_commit.id.truncate(7)"

#自定义 Interceptor 示例

  1. 创建自定义 interceptor 的 Deployment:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: custom-interceptor
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: custom-interceptor
      template:
        metadata:
          labels:
            app: custom-interceptor
        spec:
          containers:
            - name: custom-interceptor
              image: custom-interceptor:latest
              ports:
                - containerPort: 8080
  2. 创建自定义 interceptor 的 Service:

    apiVersion: v1
    kind: Service
    metadata:
      name: custom-interceptor-svc
    spec:
      selector:
        app: custom-interceptor
      ports:
        - port: 80
          targetPort: 8080
  3. 注册自定义 interceptor:

    apiVersion: triggers.tekton.dev/v1alpha1
    kind: ClusterInterceptor
    metadata:
      name: custom-interceptor
    spec:
      clientConfig:
        service:
          name: custom-interceptor-svc
          namespace: default
          port: 80

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

#CEL 表达式

CEL(Common Expression Language)是 CEL interceptor 中用于过滤和转换事件数据的强大工具。

#适用场景

  • 基于复杂条件过滤事件
  • 从事件负载中提取特定数据
  • 基于现有数据创建新字段
  • 实现条件逻辑

#约束和限制

  • 复杂表达式可能难以调试
  • 功能受限于 CEL 提供的能力
  • 非常复杂的表达式可能影响性能

#原则/参数说明

常见 CEL 模式:

  • 访问 body 字段:body.repository.full_name
  • 访问 header 字段:header.X-GitHub-Event
  • 字符串操作:body.ref.split('/')[2]
  • 条件判断:body.action in ['opened', 'reopened', 'synchronize']
  • 布尔逻辑:body.pull_request.base.ref == 'main' && body.action == 'opened'

#配置示例

- ref:
    name: "cel"
  params:
    - name: "filter"
      value: "header.match('X-GitHub-Event', 'pull_request') && body.action in ['opened', 'reopened', 'synchronize']"
    - name: "overlays"
      value:
        - key: branch_name
          expression: "body.pull_request.head.ref"
        - key: is_main_target
          expression: "body.pull_request.base.ref == 'main'"

#HTTPS 配置

建议使用 HTTPS 运行 interceptor,未来版本将强制要求。

#适用场景

  • 生产环境
  • 处理敏感数据
  • 满足安全合规要求

#约束和限制

  • 需要妥善管理证书
  • 相较 HTTP 需要额外配置

#原则/参数说明

配置 interceptor 使用 HTTPS:

  1. 在 interceptor 上添加 server/type: https 标签
  2. 提供用于证书验证的 CA bundle
  3. 确保 interceptor 服务配置为提供 HTTPS 服务

#配置示例

apiVersion: triggers.tekton.dev/v1alpha1
kind: Interceptor
metadata:
  name: secure-interceptor
  labels:
    server/type: https
spec:
  clientConfig:
    caBundle: "BASE64_ENCODED_CA_BUNDLE"
    service:
      name: secure-interceptor-svc
      namespace: default
      port: 8443

#参考资料

  • Tekton Triggers Interceptors Documentation
  • Namespaced Interceptors Documentation
  • Cluster Interceptors Documentation
  • CEL Language Specification
  • Implementing Custom Interceptors