Alauda DevOps Pipelines Docs
  • 简体中文

    • Pipeline Integration

    目录

    Overview什么是流水线集成流水线集成关键字段注解中的存储流水线集成结构名称ResourceInterface 引用Connector 引用参数属性工作空间任务集成支持示例References

    Overview

    在使用 Tekton 构建 CI/CD 流水线时，开发者常常需要与外部资源集成，例如 Git 仓库、容器镜像仓库和制品仓库。传统方式需要手动配置每个外部工具的 URL、凭证和参数，这不仅容易出错且耗时。

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

    • 便捷的资源浏览与选择：通过 UI 辅助浏览并添加 Git 仓库、Git Revision、OCI 仓库及其他资源，无需手动输入
    • 统一的资源属性：将同一远程资源的拆分属性作为整体处理，避免分别配置 url 和 revision 参数及工作空间配置
    • 引导式工作空间设置：快速设置相关连接器的工作空间，并清晰指引每个工作空间应使用的连接器类型
    • 保持灵活性：在保留现有编排和流水线执行体验的同时，增加强大的连接器能力

    什么是流水线集成

    流水线集成是通过 Connectors 和 ResourceInterfaces 将外部资源与 Tekton 任务和流水线连接的机制。它定义了：

    • 流水线工作流中使用的资源和连接器
    • 资源所需的参数配置
    • 资源输出与流水线参数之间的属性映射
    • 卷和凭证的工作空间映射

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

    本文档介绍流水线集成的概念和关键字段。如果您想将连接器集成到自定义流水线或任务中，应理解本文所涵盖的细节。

    内置的 Pipeline 和 Task 组件已支持流水线集成，因此您可以直接使用，无需额外配置。

    流水线集成关键字段

    流水线集成包含以下关键字段：

    • ResourceInterface 引用：指定使用哪个 ResourceInterface（按类别或名称）
    • Connector 引用：标识提供资源的 Connector 实例
    • 参数配置：ResourceInterface 所需的输入参数
    • 属性映射：资源属性如何映射到流水线/任务参数
    • 工作空间映射：资源工作空间如何映射到流水线工作空间

    注解中的存储

    集成元数据使用 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

    流水线集成结构

    名称

    流水线集成的名称。

    name: "code-repo"

    ResourceInterface 引用

    指定使用哪个 ResourceInterface。支持基于类别和基于名称的引用：

    基于类别的引用（灵活，适用于任何兼容连接器）：

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

    所有类别名称定义于 ResourceInterface 标签 resourceinterface.connectors.cpaas.io/category 中。

    基于名称的引用（特定接口）：

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

    使用场景：

    • 对于应支持不同 ResourceInterface 实现的可复用流水线，使用基于类别
    • 对于需要特定 ResourceInterface 名称的流水线，使用基于名称

    Connector 引用

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

    connectorRef:
  name: "github-connector"        # 连接器名称
  namespace: "default"            # 可选，默认与流水线同命名空间
  setAtRuntime: true              # 是否在运行时选择连接器

    配置选项：

    • 固定连接器：设置 name 和 namespace，setAtRuntime 保持 false 或省略
    • 运行时选择：设置 setAtRuntime: true，允许在流水线执行时选择连接器
    • 默认并可覆盖：提供 name 并设置 setAtRuntime: true，支持默认值及运行时覆盖

    参数

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

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

    参数行为：

    • setAtRuntime: true 时，执行流水线时必须提供参数
    • setAtRuntime: false 或省略时，使用固定 value
    • 无 value 但 setAtRuntime: true 时，运行时需用户输入

    属性

    根据参数和连接器信息计算的输出属性及其与流水线参数的映射：

    attributes:
- name: url
  param: git-url                 # 流水线参数名（参数化时）
  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 定义的表达式计算
    • 参数化属性 通过 param 字段创建流水线参数
    • 静态属性 通过 value 字段使用固定值
    • refPath 定义属性值在流水线任务中的使用位置

    工作空间

    ResourceInterface 工作空间与流水线工作空间的映射：

    workspaces:
- name: git-source              # ResourceInterface 工作空间名称
  workspace: source-workspace   # 流水线工作空间名称
  refPath:                      # 工作空间使用位置
  - tasks.git-clone.workspaces.output
- name: git-basic-auth
  workspace: git-credentials
  refPath:
  - tasks.git-clone.workspaces.basic-auth

    工作空间配置：

    • 工作空间名称 必须匹配 ResourceInterface.spec.workspaces[].name
    • 流水线工作空间 根据 workspace 字段自动创建，默认值来自 ResourceInterface.spec.workspaces[].workspaceMapping.name
    • refPath 定义该工作空间被哪个 PipelineTask 使用

    任务集成支持

    任务可以声明集成支持，实现自动参数和工作空间映射：

    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 在运行时设置

    • 连接器和仓库为固定值，revision 在运行时设置。
    • 在 git-clone 任务的 url 参数中使用固定值 https://github.com/myorg/myapp.git。
    • 在 git-clone 任务的 revision 参数中使用运行时参数 $(params.revision)。
    • 在 git-clone 任务的 source 工作空间中使用 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

    连接器、仓库和 revision 均在运行时设置

    • 连接器、仓库和 revision 均在运行时设置。
    • 在 git-clone 任务的 url 参数中使用运行时参数 $(params.git-url)。
    • 在 git-clone 任务的 revision 参数中使用运行时参数 $(params.git-revision)。
    • 在 git-clone 任务的 source 工作空间中使用 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

    References