Alauda DevOps Pipelines Docs
  • 简体中文

    • Pipeline Integration

    目录

    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