流水线集成

概述

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

将 Tekton Pipelines 与 Connectors 集成，可以通过提供一种标准化方式将外部资源连接到流水线工作流来解决这个问题。此集成可以实现：

轻松浏览和选择资源：在 UI 辅助下浏览并添加 Git 仓库、Git Revision、OCI repository 及其他资源，而无需手动输入
统一资源属性：将来自同一远程资源的拆分属性作为一个整体处理，省去单独配置 url 和 revision 参数以及 workspace 配置的需要
引导式 Workspace 设置：借助相关 connector 快速完成 workspace 设置，并清楚了解每个 workspace 适合哪种 connector 类型
保持灵活性：在增加强大的 connector 能力的同时，保留当前的编排和流水线执行体验

什么是 Pipeline Integration

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

在流水线工作流中使用哪个资源和 connector
资源所需的参数配置
资源输出与 pipeline 参数之间的属性映射
卷和凭据的 Workspace 映射

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

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

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

Pipeline Integration 关键字段

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

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 Integration 结构

名称

该 pipeline integration 的名称。

name: "code-repo"

ResourceInterface 引用

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

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

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

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

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

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

何时使用哪种方式：

对于需要适配不同 resourceinterface 实现的可复用流水线，使用基于 category
对于需要特定 resourceinterface 名称的流水线，使用基于 name

Connector 引用

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

connectorRef:
  name: "github-connector"        # Connector name
  namespace: "default"            # Optional, defaults to same namespace as pipeline
  setAtRuntime: true              # Whether to select connector at runtime

配置选项：

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

参数

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

params:
- name: repository
  value: "myorg/myapp"           # Fixed value
  setAtRuntime: false            # Not changeable at runtime
- name: revision
  value: "main"                  # Default value
  setAtRuntime: true             # Can be changed at runtime

参数行为：

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

属性

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

attributes:
- name: url
  param: git-url                 # Pipeline parameter name (when parameterized)
  transform:                     # Optional value transform
    prefix: "https://"           # Add prefix before resolved attribute value
    suffix: ".git"               # Add suffix after resolved attribute value
    accessor: "repository"       # Read sub-value (field/index) from structured attribute
  refPath:                       # Where this attribute is used
  - tasks.git-clone.params.url   # PipelineTask parameter that receives this value
- name: revision
  value: "refs/heads/main"       # Static value (no parameterization)
  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 tasks 中的使用位置

快速示例（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）

工作区

ResourceInterface workspaces 与 pipeline workspaces 之间的映射：

workspaces:
- name: git-source              # ResourceInterface workspace name
  workspace: source-workspace   # Pipeline workspace name
  refPath:                      # Where this workspace is used
  - 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 定义哪个 pipeline task 的 workspace 使用此 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 Integration

Pipeline Integration 关键字段

在注解中存储

Pipeline Integration 结构

名称

ResourceInterface 引用

Connector 引用

参数

属性

工作区

Task 集成支持

示例

参考

#流水线集成

#目录

#概述

#什么是 Pipeline Integration

#Pipeline Integration 关键字段

#在注解中存储

#Pipeline Integration 结构

#名称

#ResourceInterface 引用

#Connector 引用

#参数

#属性

#工作区

#Task 集成支持

#示例

#参考

流水线集成

目录

概述

什么是 Pipeline Integration

Pipeline Integration 关键字段

在注解中存储

Pipeline Integration 结构

名称

ResourceInterface 引用

Connector 引用

参数

属性

工作区

Task 集成支持

示例

参考