资源接口 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 添加人类可读信息。
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 默认值都为 "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 动态表单中可用的上下文变量如下:
动态表单配置方式
在 ResourceInterface 中配置动态表单有两种方式:
-
直接 API 配置:使用 descriptor 表达式直接调用 connector API。这种方式直接且易于理解。Connectors System 提供了用于列出仓库、git reference 等的 Connector API 端点。
-
在 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 的重复配置。
前提条件
- 在 ConnectorClass 中定义 OpenAPI 规范。详情请参见 ConnectorClass OpenAPI 描述。
- 添加
x-display-schema 扩展,以定义 API 如何集成到动态表单中。
Display Schema 结构
x-display-schema 扩展包含:
parameters[]:定义运行时如何填充 API 参数。
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 集成
参考资料