资源接口 ResourceInterface

概述

ResourceInterface 是一种集群级资源,用于定义外部资源(如 Git 仓库、OCI artifact、Maven artifact)的标准化抽象,以及它们如何集成到 pipeline 工作流中。它充当 connector 与 pipeline 编排之间的桥梁,使资源能够以最少的手动配置实现无缝集成。

下面的示例定义了一个 GitCodeRepository interface,用于描述 Git 仓库访问:

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  workspaces:
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

ResourceInterface 定义了资源集成的以下关键方面:

  • 资源配置所需的输入参数
  • 根据参数和 connector 信息计算得出的输出属性
  • 用于卷和凭据的 workspace 定义

本文档提供 ResourceInterface 数据结构定义 和 示例,帮助读者了解如何自定义 ResourceInterface。

除非你想自定义 ResourceInterface,否则无需了解 ResourceInterface 的细节。

解决的问题

在构建 CI/CD pipeline 时,用户通常会面临以下几个挑战:

手动填写资源:用户无法方便地浏览并添加外部资源,如 Git 仓库、OCI 仓库和其他外部服务。他们必须手动输入 URL 并设置 workspace,这既容易出错又耗时。

重复的执行配置:每次用户运行 pipeline 时,都必须手动输入版本详细信息,例如 Git revision 和目标 OCI tag,并反复配置 workspace。

属性分散:同一远程资源的属性通常会分散在不同参数中。例如,git-clone task 需要单独的 url 和 revision 参数,以及用于凭据和源代码的 workspace 配置。

复杂的 workspace 选择:pipeline workspace 选择过程会列出所有可用选项,但对于每个 workspace 应使用哪种 connector 类型,几乎没有提供任何指导。

ResourceInterface 通过提供一种标准化方式来描述并将外部资源集成到 pipeline 工作流中,从而解决这些问题,使用户能够通过 UI 界面浏览并选择资源,同时自动生成正确的配置和凭据。

数据结构

ResourceInterface 是一种集群级 k8s 资源

  • Kind: ResourceInterface
  • API Version: connectors.alauda.io/v1alpha1

人类可读信息

ResourceInterface 是一个标准的 k8s 资源,可以通过 annotations 添加人类可读信息。

KeyPositionDescription
cpaas.io/display-nameannotationsResourceInterface 的显示名称,可选。
cpaas.io/descriptionannotationsResourceInterface 的描述,可选。
apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    cpaas.io/display-name: "Git Code Repository"
    cpaas.io/description: "GitCodeRepository is a resource interface for Git code repository"

你也可以使用 style.tekton.dev/descriptors annotation 来描述动态表单的参数。

metadata:
  annotations:
    style.tekton.dev/descriptors: |-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs

更多详情请参考 dynamic-form。

资源类别

ResourceInterface 会将资源组织为定义通用契约和行为的类别。类别通过 label resourceinterface.connectors.cpaas.io/category 标记。

metadata:
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"

多个 ResourceInterface 可以属于同一个类别(例如,gitcoderepository 和 githubcoderepository 都属于 GitCodeRepository 类别)。同一类别中的资源必须提供相同的标准属性和 workspace,以确保兼容性。

参数

参数定义了资源在集成到 pipeline 时所需的输入数据。这些参数会影响输出属性的计算。

参数定义在 spec.params 中,并遵循 Tekton 参数类型:

  • name: 参数名称
  • type: 支持 string、array、object(与 Tekton ParamSpec 类型一致)
  • default: 默认参数值(可选)
  • description: 参数描述,用于 UI 展示(可选)

例如:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"

属性

属性定义了根据输入参数和 connector 信息计算出的输出值。它们可以作为参数被 pipeline task 消费,也可以提升为 pipeline 级参数。

属性定义在 spec.attributes 中:

  • name: 属性名称
  • type: 值类型 - 支持 string、array
  • expression: 用于计算属性值的 JavaScript 表达式
  • parameterize: 参数化配置
    • name: 参数化后使用的默认参数名
    • disable: 是否禁用参数化
  • dependsOn: 对参数或 connector 的依赖

例如:

spec:
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector

表达式语法

表达式使用 JavaScript 语法,并支持:

  • 字符串拼接: params.organization + '/' + params.repository
  • 对象属性访问: connector.metadata.name
  • 数组操作: params.tags.map(tag => connector.spec.address + ':' + tag)
  • 内置函数:
    • url(connector.spec.address).host: 获取地址的 host

也支持其他 JavaScript 语法。

可用上下文:

  • connector: 当前 connector 信息,connector 的结构请参考 Connector 的概念
  • params: 当前参数值

上下文数据结构如下:

{
  "params": {
    "param-name1": "param-value",
    "param-name2": "param-value"
  },
  "connector": {}
}

安全性:前端在沙箱环境中执行 JavaScript 代码,只允许安全的、受沙箱限制的函数。

示例:

  • {connector.spec.address + '/' + params.repository}: 获取仓库地址
  • {url(connector.spec.address).host + '/' + params.repository + ':' + params.tag}: 获取 artifact 地址
  • {params.tags.map(tag => url(connector.spec.address).host + '/' + params.repository + ':' + tag)}: 通过遍历 tags 数组获取 artifact 数组的地址

依赖项

依赖项指定属性计算依赖哪些参数或 connector 信息:

  • params.<param-name>: 依赖某个特定参数值
  • connector: 依赖 connector 选择

工作区

工作区定义了由 resource interface 提供的卷和凭据。它们使 pipeline task 能够自动获取所需资源。

工作区定义在 spec.workspaces 中:

  • name: 工作区名称
  • workspaceMapping.name: 添加到 pipeline workspaces 时使用的默认 workspace 名称
  • value: 默认 workspace 值(遵循 Tekton WorkspaceBinding 格式),与 Tekton WorkspaceBinding 类型一致

例如:

spec:
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 1Gi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

workspace 值支持使用与属性相同的语法,通过表达式动态引用参数和 connector 值。

ConnectorClass

ConnectorClass 通过 label resourceinterface.connectors.cpaas.io/<resource-interface-name>: "true" 标记其支持的 ResourceInterface,例如:

metadata:
  labels:
    resourceinterface.connectors.cpaas.io/gitcoderepository: "true"
    resourceinterface.connectors.cpaas.io/githubcoderepository: "true"

这使系统能够将兼容的 connector 与 ResourceInterface 匹配,并根据 ResourceInterface 定义提供合适的参数表单。

有关 ConnectorClass 的更多信息,请参考 ConnectorClass 的概念

Schema Version 和 Tekton 兼容性

ResourceInterface 带有两个与版本相关的 label,它们各自用于不同目的:

Label目的
resourceinterface.connectors.cpaas.io/version标识同一 RI 对象的连续代,例如 gitcoderepository-v1 和 gitcoderepository-v2 可以同时存在于集群中。当前该 label 仅用于消除对象名称歧义——目前还没有 controller 或运行时路径使用它。
resourceinterface.connectors.cpaas.io/schema-version声明该 RI 所需的前端渲染能力(sandbox 函数、表单 widget、表达式语法)。DevOps UI 会声明自己的 currentSchema,并静默跳过任何 schema-version 高于自身支持级别的 RI。

如果未提供,这两个 label 默认值都为 "1"。本节其余部分将介绍 schema-version 维度,这也是 Tekton 兼容性体现的地方。

与 Tekton 版本的兼容性

在能够识别 schema-version label 的 Tekton 版本中,DevOps 前端会针对每个类别自动选择 schema-version 不高于其自身支持级别的最高版本 ResourceInterface。无需任何 operator 配置——混合 schema 的部署可以开箱即用。

在不支持 schema-version、且早于该能力的旧 Tekton 版本中,前端会将所有已安装的 ResourceInterface 都视为可渲染。对于某个类别,如果唯一的 ResourceInterface 的 schema-version > 1,那么选择一个 Connector 会生成损坏或空白的集成表单——前端无法解析更高 schema 的表达式、workspace 配置或表单 widget。

从损坏表单症状中恢复

如果你在较旧的 Tekton 版本中遇到上述损坏表单症状,可以按以下两种路径恢复——按优先级排序:

首选:升级 Tekton operator

将你的 Tekton 版本升级到能够识别 schema-version label 的版本。这是根本修复方案:

  • 之后 DevOps 前端会透明地选择其自身 currentSchema 支持的最高 ResourceInterface,并静默跳过超出范围的项;无需任何 Connectors-operator 配置,损坏表单症状将消失。
  • ConnectorsConfig.spec.installFlags 保持为空(默认值),因此只要 Tekton 能够渲染,所有已发布的 ResourceInterface 都会被安装并可用。
  • 不会引入技术债务——你不需要记住以后再撤销紧急覆盖配置。

如果你的环境允许升级 Tekton,建议优先采用此方案,到此即可结束。

回退方案:限制已安装的 schema-version 范围

如果你暂时无法升级 Tekton,可以在集群单例 ConnectorsConfig 上限制可安装的 schema-version:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
spec:
  installFlags:
    pipeline-integration: "<=2"   # install schema-version 1 and 2; skip 3+

更高 schema 的 ResourceInterface 会从集群中移除;各类别会回退到你的 Tekton 能够渲染的版本。待 Tekton 升级后,可以提高该上限(例如 "<=3")或移除该配置项以重新安装它们。

完整的 ConnectorsConfig 参考请见 安装 → ConnectorsConfig。

动态表单

动态表单提供了一种声明式方式,用于为 Pipeline 集成配置交互式 UI 组件。借助动态表单,用户可以通过 connector 直接浏览并选择诸如 Git 仓库和 revision 之类的资源。

概述

使用 style.tekton.dev/descriptors annotation 为参数定义动态表单行为。示例如下:

metadata:
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

其语法遵循 Pipeline 动态表单 规范。建议在继续之前先熟悉该文档。

除了标准能力之外,ResourceInterface 中的动态表单还支持:

  • 扩展上下文变量,用于访问 connector 和 ResourceInterface 数据
  • 在 ConnectorClass 中引用 OpenAPI display schema,以实现 API 配置集中化,并在使用动态表单时引用 API 定义

扩展上下文变量

ResourceInterface 动态表单中可用的上下文变量如下:

变量描述
context.connectorConnector 对象。可访问任意字段,例如 context.connector.status.api.path
context.connectorClassConnectorClass 对象。可访问任意字段,例如 context.connectorClass.spec.api.openapi
context.paramsPipeline 集成 UI 表单中的参数值,例如 context.params.repository
context.resourceInterfaceResourceInterface 对象。可根据需要访问任意字段

动态表单配置方式

在 ResourceInterface 中配置动态表单有两种方式:

  1. 直接 API 配置:使用 descriptor 表达式直接调用 connector API。这种方式直接且易于理解。Connectors System 提供了用于列出仓库、git reference 等的 Connector API 端点。

  2. 在 ConnectorClass 中引用 OpenAPI Display Schema:在 ConnectorClass 中通过 spec.api.openapi 定义 API 调用和展示映射。这种方式将 API 定义和展示配置集中管理,避免在多个 ResourceInterface 中重复配置。在使用动态表单时,你可以直接引用 ConnectorClass 中的 API 定义。

你可以单独使用任一种方式,也可以按需组合使用。

直接 API 配置

示例:列出 GitLab 仓库

GitLab connector 暴露了原生 GitLab API,可用于填充仓库选择器:

kind: ResourceInterface
metadata:
  name: gitlabcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

示例:列出 Git 引用

Git connector 提供了 gitrefs 端点,用于列出分支和 tag:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:revision
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/git/gitrefs?repositoryUrl=${context.connector.spec.address + "/" + context.params.repository + ".git"}&search=${current.search}
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:expression:props.options:label:path:name
          - urn:alm:descriptor:expression:props.options:value:path:name
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

引用 OpenAPI Display Schema 于 ConnectorClass

为了集中管理 API 定义和展示配置,请在 ConnectorClass 中使用 spec.api.openapi 进行定义。随后,动态表单即可直接引用这些定义,从而消除跨多个 ResourceInterface 的重复配置。

前提条件

  1. 在 ConnectorClass 中定义 OpenAPI 规范。详情请参见 ConnectorClass OpenAPI 描述。
  2. 添加 x-display-schema 扩展,以定义 API 如何集成到动态表单中。

Display Schema 结构

x-display-schema 扩展包含:

  • parameters[]:定义运行时如何填充 API 参数。
    • name:参数名称(必须与 API 参数名称匹配)
    • value:参数值表达式。语法遵循 Pipeline 动态表单。
  • descriptors:定义 API 响应数据如何映射到表单选项。语法遵循 Pipeline 动态表单。

示例:Git References API

下面的 ConnectorClass 配置定义了带有 display schema 的 GET /git/gitrefs API:

  • repositoryUrl 参数设置为 ${context.connector.spec.address + "/" + context.params.repository + ".git"},并作为 query 参数传递
  • search 参数设置为 ${current.search},用于过滤结果
  • 响应中的 items 数组被映射为选择项,使用 name 作为 label 和 value

例如:

kind: ConnectorClass
spec:
  api:
    openapi:
      openapi: 3.0.3
      info:
        title: Git API
        version: v1alpha1
      paths:
        /git/gitrefs:
          get:
            x-provider-type: api
            x-display-schema:
              parameters:
              - name: repositoryUrl
                value: ${context.connector.spec.address + "/" + context.params.repository + ".git"}
              - name: search
                value: ${current.search}
              descriptors:
              - urn:alm:descriptor:expression:props.options:path:items
              - urn:alm:descriptor:expression:props.options:label:path:name
              - urn:alm:descriptor:expression:props.options:value:path:name
            operationId: listGitRefs
            parameters:
            - name: repositoryUrl
              in: query
              description: "Cloneable URL of the repository (e.g., https://github.com/mygroup/my-app.git)"
              required: true
              schema:
                type: string
            - name: search
              in: query
              description: "Return list of git references containing the search string"
              required: false
              schema:
                type: string
            responses:
              '200':
                description: "All git references for a repository"
                content:
                  application/json: {}

在 ResourceInterface 中引用 OpenAPI

一旦 API 在 ConnectorClass 中定义,就可以使用以下语法在 ResourceInterface 中引用它:

  • urn:alm:descriptor:widgets:select 用于指定 widget 类型
  • schema:openapi:context.connectorClass.spec.api.openapi:<operationId> 用于引用 ConnectorClass 中的 API 定义

例如:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

通过此配置,Pipeline 集成中的 revision 字段会以 dropdown 形式呈现,并从 listGitRefs API 获取选项。

示例

GitCodeRepository ResourceInterface

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: revision
    type: string
    expression: "{params.revision}"
    parameterize:
      name: git-revision
    dependsOn:
    - params.revision
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 200Mi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

OCIArtifact ResourceInterface

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: ociartifact
  labels:
    resourceinterface.connectors.cpaas.io/category: "OCIArtifact"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: tags
    type: array
    description: "Image tags"
  attributes:
  - name: repository-address
    type: string
    expression: "{connector.spec.registry + '/' + params.repository}"
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector
  workspaces:
  - name: registry-config
    workspaceMapping:
      name: registry-config
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "config"
          token.expiration: 60m

下一步

  • 当你希望在自定义 Pipeline 或 Task 中集成 Connector 时,请了解 Pipeline 集成

参考资料