Pipeline 集成

概述

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

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

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

什么是 Pipeline 集成

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

pipeline workflow 中应使用哪个 resource 和 connector
资源所需的参数配置
资源输出与 pipeline 参数之间的属性映射
卷和凭据的workspace 映射

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

本文档介绍 Pipeline 集成的概念和关键字段。如果你想将 connectors 集成到自定义 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 集成结构

名称

该 pipeline 集成的名称。

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:
  name: "gitcoderepository"
  apiVersion: "connectors.alauda.io/v1alpha1"

何时使用哪种方式：

对于需要支持不同 resourceinterfaces 实现的可复用 pipeline，请使用 基于 category 的方式
对于需要特定 resourceinterface 名称的 pipeline，请使用 基于 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，允许在 pipeline 执行期间选择 connector
默认值可覆盖：提供 name 并设置 setAtRuntime: true，即可在运行时覆盖默认 connector

参数

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

属性

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

attributes:
- name: url
  param: git-url                 # Pipeline parameter name (when parameterized)
  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 字段指定）
refPath 定义属性值在 pipeline tasks 中的使用位置

Workspaces

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 定义了该 workspace 被哪个 pipelinetask 的 workspace 使用

Task 集成支持

Tasks 可以声明集成支持，以启用自动参数和 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 集成结构

名称

ResourceInterface 引用

Connector 引用

参数

属性

Workspaces

Task 集成支持

示例

参考资料

#Pipeline 集成

#目录

#概述

#什么是 Pipeline 集成

#Pipeline 集成关键字段

#存储在注解中

#Pipeline 集成结构

#名称

#ResourceInterface 引用

#Connector 引用

#参数

#属性

#Workspaces

#Task 集成支持

#示例

#参考资料

Pipeline 集成

目录

概述

什么是 Pipeline 集成

Pipeline 集成关键字段

存储在注解中

Pipeline 集成结构

名称

ResourceInterface 引用

Connector 引用

参数

属性

Workspaces

Task 集成支持

示例

参考资料