Pipeline 集成

概述

在使用 Tekton 构建 CI/CD pipeline 时，开发者通常需要与外部资源集成，例如 Git repository、container registry 和 artifact repository。传统上，这需要为每个外部工具手动配置 URL、credentials 和参数，既容易出错，又耗时。

将 Tekton Pipelines 与 Connectors 集成，可以通过一种标准化方式将外部资源连接到 pipeline workflow，从而解决这个问题。此集成支持：

轻松浏览和选择资源：通过 UI 辅助浏览并添加外部资源，例如 Git repository、Git Revision、OCI repository 和其他资源，而不是手动输入
统一资源属性：将来自同一远程资源的分离属性作为一个整体处理，无需分别配置 url 和 revision 参数以及 workspace 配置
引导式 workspace 设置：借助相关 connector 快速完成 workspace 设置，并清晰说明每个 workspace 适合使用哪种 connector 类型
保持灵活性：在保留当前编排和 pipeline 执行体验的同时，增加强大的 connector 能力

什么是 Pipeline 集成

Pipeline 集成是将外部资源（通过 Connectors 和 ResourceInterfaces）与 Tekton Task 和 Pipeline 连接起来的机制。它定义：

在 pipeline workflow 中使用哪个 resource 和 connector
资源所需的参数配置
资源输出与 pipeline 参数之间的属性映射
用于 volume 和 credentials 的 workspace 映射

PipelineIntegration 不是一个实际的 Kubernetes 资源，而是存储在 Tekton Pipeline 或 Task 注解中的集成元数据，使用 integrations.tekton.dev/integrations 键。

本文档介绍 Pipeline 集成的概念和关键字段。如果你希望将 connector 集成到自定义 pipeline 或 task 中，应了解本文档中涵盖的细节。

内置的 Pipeline 和 Task 组件已经支持 Pipeline 集成，因此你可以直接使用它们，无需任何额外配置。

Pipeline 集成关键字段

一个 Pipeline 集成包含以下关键字段：

ResourceInterface 引用：指定要使用的 ResourceInterface（按 category 或 name）
Connector 引用：标识提供该资源的 Connector 实例
参数配置：ResourceInterface 所需的输入参数
属性映射：资源属性如何映射到 pipeline/task 参数
Workspace 映射：资源 workspace 如何映射到 pipeline workspace

存储在注解中

集成元数据使用 integrations.tekton.dev/integrations 注解，以 YAML 数组形式存储：

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  annotations:
    integrations.tekton.dev/integrations: |
      - name: code-repo
        interface:
          category: "GitCodeRepository"
        connectorRef:
          name: github-connector
          namespace: default
          setAtRuntime: false
        params:
        - name: repository
          value: "myorg/myapp"
          setAtRuntime: false
        - name: revision
          setAtRuntime: true
        attributes:
        - name: url
          param: git-url
          refPath:
          - tasks.git-clone.params.url
        - name: revision
          param: git-revision
          refPath:
          - tasks.git-clone.params.revision
        workspaces:
        - name: git-source
          workspace: source-workspace
          refPath:
          - tasks.git-clone.workspaces.output

Pipeline 集成结构

Name

pipeline integration 的名称。

name: "code-repo"

ResourceInterface 引用

指定要使用的 ResourceInterface。支持基于 category 和基于 name 的引用：

基于 category 的引用（灵活，适用于任何兼容的 connector）：

interface:
  apiVersion: "connectors.alauda.io/v1alpha1"
  category: "GitCodeRepository"

所有 category 名称都定义在名为 resourceinterface.connectors.cpaas.io/category 的 ResourceInterface 标签中。

基于 name 的引用（特定 interface）：

interface:
  name: "gitcoderepository"
  apiVersion: "connectors.alauda.io/v1alpha1"

何时使用哪种方式：

对于需要适配不同 resourceinterfaces 实现的可复用 pipeline，使用基于 category 的方式
对于需要特定 resourceinterface 名称的 pipeline，使用基于 name 的方式

Connector 引用

指定用于访问外部资源的 Connector 实例：

connectorRef:
  name: "github-connector"        # Connector 名称
  namespace: "default"            # 可选，默认为与 pipeline 相同的 namespace
  setAtRuntime: true              # 是否在运行时选择 connector

配置选项：

固定 Connector：设置 name 和 namespace，将 setAtRuntime 保持为 false 或省略
运行时选择：设置 setAtRuntime: true，允许在 pipeline 执行期间选择 connector
默认值并支持覆盖：提供 name 并设置 setAtRuntime: true，以便使用默认值并支持运行时覆盖

参数

ResourceInterface 所需的输入参数。这些参数用于计算资源属性：

params:
- name: repository
  value: "myorg/myapp"           # 固定值
  setAtRuntime: false            # 运行时不可更改
- name: revision
  value: "main"                  # 默认值
  setAtRuntime: true             # 可在运行时更改

参数行为：

当 setAtRuntime: true 时，执行 pipeline 时必须提供该参数
当 setAtRuntime: false 或省略时，参数使用固定的 value
没有 value 但设置了 setAtRuntime: true 的参数，需要用户在运行时输入

属性

根据参数和 connector 信息计算得到的输出属性，以及它们到 pipeline 参数的映射：

attributes:
- name: url
  param: git-url                 # Pipeline 参数名称（在参数化时）
  transform:                     # 可选的值转换
    prefix: "https://"           # 在解析后的属性值前添加前缀
    suffix: ".git"               # 在解析后的属性值后添加后缀
    accessor: "repository"       # 从结构化属性中读取子值（字段/索引）
  refPath:                       # 此属性的使用位置
  - tasks.git-clone.params.url   # 接收该值的 PipelineTask 参数
- name: revision
  value: "refs/heads/main"       # 静态值（不进行参数化）
  refPath:
  - tasks.git-clone.params.revision

属性配置：

属性名称必须与 ResourceInterface.spec.attributes[].name 匹配
属性值使用 ResourceInterface.spec.attributes[].expression 中定义的表达式计算
参数化属性会创建 pipeline 参数（通过 param 字段指定）
静态属性使用固定值（通过 value 字段指定）
transform 可在映射前对解析后的属性值进行调整：
- prefix：在属性值前添加前缀字符串
- suffix：在属性值后添加后缀字符串
- accessor：从结构化属性中选择子值：
  - 对于数组属性，使用索引（例如 "0"）
  - 对于对象属性，使用字段名（例如 "repository"）
  - accessor 选择子值后，结果属性值会转换为 string
refPath 定义属性值在 pipeline task 中的使用位置

快速示例（transform）

attributes:
- name: artifacts
  param: chartRef
  transform:
    accessor: "0"
    prefix: "oci://"
    suffix: "-prod"

如果解析后的 artifacts 值为 ["registry.example.com/team/app"]，则此映射会使用第一个项，并生成 oci://registry.example.com/team/app-prod。

当属性是数组/对象且你只需要其中一个项/字段时，使用 accessor
当下游 task 需要固定协议或字面量前缀时，使用 prefix（例如 oci://）
当下游 task 需要固定后缀，例如环境标记时，使用 suffix（例如 -prod）

Workspaces

ResourceInterface workspaces 与 pipeline workspaces 之间的映射：

workspaces:
- name: git-source              # ResourceInterface workspace 名称
  workspace: source-workspace   # Pipeline workspace 名称
  refPath:                      # 此 workspace 的使用位置
  - tasks.git-clone.workspaces.output
- name: git-basic-auth
  workspace: git-credentials
  refPath:
  - tasks.git-clone.workspaces.basic-auth

Workspace 配置：

Workspace 名称必须与 ResourceInterface.spec.workspaces[].name 匹配
Pipeline workspace 会自动使用 workspace 字段中指定的值创建，默认值来自 ResourceInterface.spec.workspaces[].workspaceMapping.name
refPath 定义该 workspace 被哪个 pipelinetask 的 workspace 使用

Task 集成支持

Task 可以声明集成支持，以启用自动参数和 workspace 映射：

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: git-clone
  annotations:
    integrations.tekton.dev/integrations: |
      - name: code-repo
        interface:
          category: Git Code Repository
        attributes:
        - name: url
          param: git-url
        - name: revision
          param: git-revision
        workspaces:
        - name: source
          workspace: output
        - name: credentials
          workspace: basic-auth
spec:
  params:
  - name: git-url
    type: string
  - name: revision
    type: string
  workspaces:
  - name: output
  - name: basic-auth

示例

Revision 在运行时设置

connector 和 repository 使用固定值，revision 在运行时设置。
在 git-clone task 的 url 参数中使用固定值 https://github.com/myorg/myapp.git。
在 git-clone task 的 revision 参数中使用运行时参数 $(params.revision)。
在 git-clone task 的 source workspace 中使用 workspace source-workspace。

例如：

- name: app-source
  interface:
    category: "GitCodeRepository"
  connectorRef:
    name: github-connector
    namespace: default
  params:
  - name: repository
    value: "myorg/myapp"
  - name: revision
    setAtRuntime: true
  attributes:
  - name: url
    value: "https://github.com/myorg/myapp.git"
    refPath:
    - tasks.git-clone.params.url
  - name: revision
    value: "$(params.revision)"
    refPath:
    - tasks.git-clone.params.revision
  workspaces:
  - name: git-source
    workspace: source-workspace
    refPath:
    - tasks.git-clone.workspaces.output

connector、repository 和 revision 都在运行时设置

connector、repository 和 revision 都在运行时设置。
在 git-clone task 的 url 参数中使用运行时参数 $(params.git-url)。
在 git-clone task 的 revision 参数中使用运行时参数 $(params.git-revision)。
在 git-clone task 的 source workspace 中使用 workspace source-workspace。

例如：

- name: app-source
  interface:
    category: "GitCodeRepository"
    apiVersion: "connectors.alauda.io/v1alpha1"
  connectorRef:
    setAtRuntime: true
  params:
  - name: repository
    setAtRuntime: true
  - name: revision
    setAtRuntime: true
  attributes:
  - name: url
    param: git-url
    value: $(params.git-url)
    refPath:
    - tasks.git-clone.params.url
  - name: revision
    param: git-revision
    value: $(params.git-revision)
    refPath:
    - tasks.git-clone.params.revision
  workspaces:
  - name: git-source
    workspace: source-workspace
    refPath:
    - tasks.git-clone.workspaces.output

Pipeline 集成

目录

概述

什么是 Pipeline 集成

Pipeline 集成关键字段

存储在注解中

Pipeline 集成结构

Name

ResourceInterface 引用

Connector 引用

参数

属性

Workspaces

Task 集成支持

示例

参考

#Pipeline 集成

#目录

#概述

#什么是 Pipeline 集成

#Pipeline 集成关键字段

#存储在注解中

#Pipeline 集成结构

#Name

#ResourceInterface 引用

#Connector 引用

#参数

#属性

#Workspaces

#Task 集成支持

#示例

#参考

Pipeline 集成

目录

概述

什么是 Pipeline 集成

Pipeline 集成关键字段

存储在注解中

Pipeline 集成结构

Name

ResourceInterface 引用

Connector 引用

参数

属性

Workspaces

Task 集成支持

示例

参考